Error Handling

Klarna's error handling: how the APIs communicate failures through error codes, messages, and HTTP status codes to support troubleshooting.

When an API call fails, Klarna responds with a 4xx or 5xx HTTP status code and a response body containing an error object. Use the HTTP status code together with the error_code to build your error-handling logic.

Field	Description
`error_id`	A unique identifier for the request, generated by Klarna. Include it when contacting support.
`error_code`	A machine-readable code categorizing the error. Build your error-handling logic on this value.
`error_message`	A human-readable message for technical troubleshooting. It is not meant to be shown to customers.
`validation_errors`	For `VALIDATION_ERROR`, an array of `{ parameter, reason, doc_url }` objects detailing each failed parameter.
`doc_url`	When available, a link to documentation explaining how to avoid the error.

Branch your error handling on the HTTP status code and error_code — not on error_message, which is free text and may change. 4xx codes indicate a client-side issue to fix before retrying; 5xx codes are server-side and may be retried after a short delay. Always log the error_id and include it when contacting Klarna support.

Example error response:

JSON

1 2 3 4 5 6 7 8 9 10

{
  "error_id": "abcd1234-12ab-1234-abcd-abcd12345678",
  "error_code": "VALIDATION_ERROR",
  "error_message": "One or more input parameters failed validation",
  "validation_errors": [
    {
      "parameter": "line_items[0].quantity",
      "reason": "Parameter line_items[0].quantity must be greater than or equal to 1",
      "doc_url": "https://docs.klarna.com/"
    }

Error codes

Error code	HTTP status	Description	Handling
`CUSTOMER_TOKEN_REVOKED`	409	The customer token referenced by the resource has been revoked.	Have the customer re-authenticate to obtain a new token; the revoked token cannot be reused.
`INTERNAL_ERROR`	500	An unexpected error occurred in the API. The request may be retried without modification after a delay.	Retry after a short delay. If the error persists, contact Klarna support with the `error_id`.
`INVALID_CONTENT_TYPE`	400	The input does not conform to the expected content type syntax. For example invalid JSON.	Verify the request's Content-Type header and body match what the API expects.
`OPERATION_FORBIDDEN`	403	Insufficient privileges to perform the requested operation on the resource.	Ensure the credentials being used have the necessary permissions for this operation.
`RATE_LIMITED`	429	The request was rate limited. All requests from this client are temporarily rate limited.	Back off and retry after a delay. Repeated requests without backoff may extend the rate-limit window.
`RESOURCE_CONFLICT`	409	There was a conflict in using the resource. Idempotency violation or concurrent updates to a resource occurred.	Check for retried or concurrent requests against the same resource before retrying.
`RESOURCE_NOT_FOUND`	404	The requested resource was not found.	Verify the identifier in the request path. This can also occur when acting on an expired or already-completed resource.
`TEMPORARY_UNAVAILABLE`	503	The system is temporarily unavailable to process the request. The request may be retried without modification after a delay.	Retry after a short delay, using the same backoff as for rate-limited requests.
`TIMEOUT`	500	The request timed out due to exceeding the threshold for the API operation or the default configured in the platform.	Retry using the same backoff as for rate-limited requests. If the error persists, contact Klarna support with the `error_id`.
`UNAUTHORIZED`	401	The request was not authorized.	Verify the credentials, check the authentication method, and confirm you're calling the correct endpoint.
`VALIDATION_ERROR`	400	An input parameter failed input validation. For example exceeding a max value, or failed pattern matching.	Check `validation_errors` for the specific parameters that failed, and verify the request format.