Error Handling

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

4 min read

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
`CARD_REGISTRATION_REJECTED`	400	The card registration request was rejected (e.g. malformed card details, an invalid card, or no available connector).	Check `reason_message` (and `rejection_context` for `invalid_card`) for the specific rejection reason. Some issuer rejections indicate a retry won't succeed — prompt the customer for a different card in those cases.
`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.
`IDEMPOTENCY_KEY_MISMATCH`	422	The Klarna-Idempotency-Key was reused with a different request body.	Use a new idempotency key for requests with a different body, or resend the original request body unchanged.
`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.
`MIGRATION_NOT_ALLOWED`	409	The merchant_id cannot be migrated in its current state, for example because it is disabled on Klarna Payments.	Do not retry unchanged. Contact your Klarna representative to resolve its state, then resubmit the same payload.
`MTLS_ENFORCEMENT_REMOVAL_NOT_ALLOWED`	409	mTLS enforcement cannot be removed in the account's current state: enforcement is active, or mTLS authentication is required to perform the removal.
`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.

Jump to section...