Błędy

Odpowiedzi błędów korzystają ze spójnego formatu JSON. W tym miejscu są omówione najczęstsze błędy, które mogą pojawić się przy przy wysyłaniu faktur, odpytywaniu o stan i pobieraniu UPO XML.

Obiekt błędu

Treść odpowiedzi zawiera obiekt error.

  • typestring

    Rodzina błędu, np. invalid_request_error, authentication_error, validation_error, conflict_error, rate_limit_error lub api_error.

  • codestring

    Stabilny produktowy kod błędu, np. missing_idempotency_key lub upo_not_available.

  • messagestring

    Komunikat czytelny dla człowieka.

  • paramstring | null

    Parametr lub nagłówek powiązany z błędem, jeśli jest dostępny.

  • request_idstring

    Odpowiada nagłówkowi odpowiedzi Request-Id generowanemu przez serwer.

  • retryableboolean

    Czy klient może ponowić żądanie później. Nie oznacza to, że każde ponowienie jest bezpieczne z nową treścią żądania lub nowym kluczem idempotentności.

Uwierzytelnianie

Deweloperskie endpointy faktur wymagają prawidłowego deweloperskiego klucza API przekazanego jako bearer.

Brak deweloperskiego klucza API
{  "error": {    "type": "authentication_error",    "code": "missing_api_key",    "message": "Provide a valid bearer API key.",    "param": null,    "request_id": "req_0Y9a6cW9xQz9xwWzYxA0fY",    "retryable": false  }}

Idempotency-Key

POST /v1/invoices wymaga nagłówka Idempotency-Key.

Brak nagłówka Idempotency-Key
{  "error": {    "type": "invalid_request_error",    "code": "missing_idempotency_key",    "message": "Provide an Idempotency-Key header.",    "param": "Idempotency-Key",    "request_id": "req_0Y9a6cW9xQz9xwWzYxA0fY",    "retryable": false  }}

Konflikt idempotentności

Ponowne użycie tego samego Idempotency-Key z innym kanonicznym żądaniem zwraca idempotency_conflict.

Konflikt idempotentności
{  "error": {    "type": "conflict_error",    "code": "idempotency_conflict",    "message": "The same idempotency key was used with a different request.",    "param": "Idempotency-Key",    "request_id": "req_0Y9a6cW9xQz9xwWzYxA0fY",    "retryable": false  }}

Walidacja faktury

Wymagane jest XML faktury. Metadane muszą być obiektem o kluczach i wartościach będących ciągami znaków.

Nieprawidłowe XML faktury
{  "error": {    "type": "validation_error",    "code": "invalid_invoice_xml",    "message": "The invoice XML is required.",    "param": "invoice_xml",    "request_id": "req_0Y9a6cW9xQz9xwWzYxA0fY",    "retryable": false  }}

Scenariusz sandboxa

Ksef-Sandbox-Scenario dotyczy wyłącznie wysyłek faktur w trybie testowym. Obsługiwane wartości to accepted, rejected, temporary_failure oraz delayed.

Nieprawidłowy scenariusz sandboxa
{  "error": {    "type": "invalid_request_error",    "code": "invalid_sandbox_scenario",    "message": "The Ksef-Sandbox-Scenario header is invalid.",    "param": "Ksef-Sandbox-Scenario",    "request_id": "req_0Y9a6cW9xQz9xwWzYxA0fY",    "retryable": false  }}

UPO niedostępne

Endpointy UPO zwracają upo_not_available, gdy faktura istnieje dla wywołującego, ale nie ma możliwości pobrania utrwalonego artefaktu UPO.

UPO niedostępne
{  "error": {    "type": "invalid_request_error",    "code": "upo_not_available",    "message": "The invoice UPO artifact is not available for this invoice.",    "param": null,    "request_id": "req_0Y9a6cW9xQz9xwWzYxA0fY",    "retryable": true  }}

Limity zapytań

API może zwrócić rate_limit_exceeded, gdy wysłano zbyt wiele żądań.

Przekroczono limit zapytań
{  "error": {    "type": "rate_limit_error",    "code": "rate_limit_exceeded",    "message": "Too many requests. Try again later.",    "param": null,    "request_id": "req_0Y9a6cW9xQz9xwWzYxA0fY",    "retryable": true  }}