Guides
Errors and error codes
Every error has a stable code for your program, a readable message and a link to this page. KSeF errors get their own API code plus KSeF's original number.
Error format
Every error is an HTTP status plus JSON with an error object. In code, rely on code: it is stable. message is for humans and may change.
{
"error": {
"type": "invalid_request_error",
"code": "buyer_nip_invalid",
"message": "buyer.nip is not a valid Polish NIP (checksum).",
"param": "order.buyer.nip",
"doc_url": "https://ksefshop.pl/api/errors#buyer_nip_invalid"
}
}
typestringrequiredError category.
One of:
invalid_request_error,authentication_error,permission_error,not_found_error,idempotency_error,rate_limit_error,invoice_error,ksef_error,api_errorcodestringrequiredStable machine-readable code. All codes
One of:
parameter_missing,parameter_invalid,body_invalid_json,body_too_large,buyer_nip_missing,buyer_nip_invalid,order_not_paid,order_cancelled,currency_not_supported,vat_rate_missing,vat_rate_unsupported,order_unprocessable,correction_requires_invoice,livemode_mismatch,resource_missing,route_not_found,method_not_allowed,pdf_not_ready,api_key_missing,api_key_invalid,live_mode_disabled,idempotency_key_reused,idempotency_key_invalid,rate_limited,internal_error,seller_not_configured,plan_limit_reached,invoice_build_failed,invoice_schema_invalid,original_not_invoiced,original_rejected,ksef_not_connected,ksef_auth_failed,ksef_duplicate_number,ksef_rejected,ksef_unavailablemessagestringrequiredHuman-readable text; may change.
paramstringJSON path of the parameter
ksef_codeintegerKSeF's own numeric code (e.g. 440 duplicate
doc_urlstringrequiredLink to the code on the errors page.
Request errors and document errors
Request errors come back at once with HTTP 4xx or 5xx and store nothing. Document errors appear later, after the API accepted the order: the queue could not build the invoice, or KSeF rejected it. The invoice then has status rejected, skipped or error, the error sits in last_error (with type invoice_error or ksef_error), and a webhook sends invoice.rejected or invoice.skipped.
type |
When |
|---|---|
invalid_request_error |
Wrong request data (400, 405, 409, 413, 422) |
authentication_error |
Missing or wrong key (401) |
permission_error |
Not allowed, e.g. live mode disabled (403) |
not_found_error |
No such object or endpoint (404) |
idempotency_error |
A problem with Idempotency-Key (400, 409) |
rate_limit_error |
Rate limit exceeded (429) |
api_error |
Our error (500) |
invoice_error |
The document cannot be built (in last_error) |
ksef_error |
A KSeF problem (in last_error) |
KSeF answers and API codes
KSeF has its own numeric codes. We turn them into API codes and keep the original number in ksef_code, so you can look it up in the KSeF documentation.
| What KSeF answered | API code | What happens next |
|---|---|---|
| Code 440: the invoice number is already used by another invoice of this seller | ksef_duplicate_number | Status rejected, ksef_code: 440. Check whether the same number was sent from another program. |
| Another rejection code, e.g. 450 (invalid invoice) | ksef_rejected | Status rejected, KSeF's code and text in ksef_code and message. |
| No answer, timeout or a code without rejection | ksef_unavailable | The document stays queued and is retried automatically. |
| Certificate or token refused (expired, revoked, no permission for the NIP) | ksef_auth_failed | Upload a new certificate or token in the panel; invoices wait. |
| No certificate or token for this mode | ksef_not_connected | Connect KSeF in the panel for test or live mode. |
| The FA(3) XML fails the XSD (checked before sending) | invoice_schema_invalid | Nothing reached KSeF. Write to us with the Request-Id or the invoice id. |
All error codes
Each code has an anchor here; doc_url points to it.
Request errors (HTTP 4xx and 5xx)
A required parameter is missing.
What to do: Add the field named in param.
A parameter has a wrong type or format.
What to do: Fix the field in param; send amounts as strings, e.g. "49.00".
The body is not valid JSON.
What to do: Serialize the body with a JSON library and send Content-Type: application/json.
The body is larger than 1 MB.
What to do: Send fewer lines (up to 1000) or split the order.
The buyer has no NIP; KSeF invoices are issued for business buyers only.
What to do: Send only orders with a NIP. Consumers do not need a KSeF invoice.
The buyer NIP fails the Polish checksum.
What to do: Validate the NIP in the cart. By hand: check a NIP.
The order is not paid; only paid orders are invoiced.
What to do: Send the order after payment is confirmed, with paid_at.
The order is cancelled.
What to do: Do not send cancelled orders.
The currency has no NBP table A rate.
What to do: Use PLN or an NBP table A currency. Foreign currency
A line has no VAT rate.
What to do: Set vat_rate on every line and shipping. In WooCommerce check that shipping is taxed.
A VAT rate other than 23, 8, 5 or 0.
What to do: Use 23, 8, 5 or 0. Exempt supplies (zw) are not supported yet.
The order cannot become an invoice (see message), e.g. a negative fee or an amount-only refund.
What to do: Turn negative fees into line discounts; describe refunds with lines or shipping. Corrections
Corrections can only be created for an invoice (inv_...), not for a correction.
What to do: Put the original invoice id in the path.
The object belongs to the other mode (test vs live).
What to do: Use a key of the mode the object was created in.
No such object, or it belongs to another account.
What to do: Check the id and that the key belongs to the right account and mode.
Unknown endpoint.
What to do: Check the path, including the /v1 prefix. Endpoints
The endpoint does not support this HTTP method.
What to do: Check the method in the reference.
The PDF is rendered shortly after KSeF accepts the invoice.
What to do: Retry in a few seconds or wait for the invoice.accepted event.
No API key.
What to do: Send Authorization: Bearer sk_test_... or sk_live_.... Authentication
The API key is wrong, revoked, or the account is disabled.
What to do: Check whether the key was rolled in the panel; copy the new one.
Live mode is not enabled for this account yet.
What to do: During early access use an sk_test_ key. Live mode will be enabled after launch.
The Idempotency-Key was used with a different request.
What to do: A new operation needs a new key; a retry repeats the same key and body. Idempotency
The Idempotency-Key must be 1-255 printable characters.
What to do: Use a short text, e.g. order-SO-1001.
Too many requests; wait for Retry-After seconds.
What to do: Wait Retry-After seconds and retry. Use webhooks instead of polling. Rate limits
Something went wrong on our side.
What to do: Retry with the same Idempotency-Key. If it repeats, write to kontakt@ksefshop.pl with the Request-Id.
Document errors (the last_error field)
Seller NIP, name or address is missing in the account.
What to do: Complete the seller data in the panel; check it with GET /v1/account.
The monthly plan limit is used up; the invoice waits without a number until there is room.
What to do: The invoice gets its number after an upgrade or in the new month, with no gaps. Live mode only.
The invoice could not be built from the order data.
What to do: Read message, fix the data and send the order with a new external_id, or write to us.
The FA(3) XML failed the official XSD.
What to do: Nothing reached KSeF. Write to us with the invoice id.
The order has no invoice to correct.
What to do: Create the invoice first and wait for accepted.
The original invoice was rejected by KSeF, so there is nothing to correct.
What to do: Resolve the original rejection; no correction is needed.
No working KSeF certificate or token for this mode.
What to do: Connect KSeF in the panel. KSeF certificate
KSeF refused the certificate or token (expired, revoked, no permission for the NIP).
What to do: Generate a new certificate or token in the KSeF taxpayer app and upload it in the panel.
KSeF 440: the invoice number is already used by another invoice of this seller.
What to do: Check that no other program uses the same numbering pattern; change the pattern in the panel.
KSeF rejected the invoice; ksef_code and message carry KSeF's own code and text.
What to do: Read KSeF's code. If it is unclear what to fix, write to us with the invoice id.
Request-Id
Every response has a Request-Id header (e.g. req_8Kq2Lm4Np6Rs8Tu0Vw2X). Log it and quote it when you write to kontakt@ksefshop.pl: it lets us find that exact request.