Errors

Error responses use a consistent JSON envelope. This page covers the errors you are most likely to handle while submitting invoices, polling state, and retrieving UPO XML.

Error object

The response body has an error object.

  • typestring

    Error family, such as invalid_request_error, authentication_error, validation_error, conflict_error, rate_limit_error, or api_error.

  • codestring

    Stable product error code, such as missing_idempotency_key or upo_not_available.

  • messagestring

    Human-readable message.

  • paramstring | null

    Parameter or header related to the error when available.

  • request_idstring

    Matches the server-generated Request-Id response header.

  • retryableboolean

    Whether the client may retry later. This does not mean every retry is safe with a new request body or a new idempotency key.

Authentication

Developer invoice endpoints require a valid bearer developer API key.

Missing developer API key
{  "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 requires Idempotency-Key.

Missing 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  }}

Idempotency conflict

Reusing the same Idempotency-Key with a different canonical request returns idempotency_conflict.

Idempotency conflict
{  "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  }}

Invoice validation

Invoice XML is required. Metadata must be an object with string keys and string values.

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

Sandbox scenario

Ksef-Sandbox-Scenario applies only to test-mode invoice submissions. Supported values are accepted, rejected, temporary_failure, and delayed.

Invalid sandbox scenario
{  "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 unavailable

UPO endpoints return upo_not_available when the invoice exists for the caller but no persisted UPO artifact can be downloaded.

UPO not available
{  "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  }}

Rate limits

The API can return rate_limit_exceeded when too many requests are sent and api_disabled when the application HTTP API is disabled for the deployment.

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