Error Handling

Klarna's error handling for Direct Partners: how the APIs communicate errors through codes, messages, and HTTP status codes to ensure smooth integration and troubleshooting.

4 min read

When an error occurs on an API request, Klarna responds with an error code, an error message and a corresponding HTTP status code.

Klarna’s APIs use HTTP status codes together with error objects to handle errors. When an API call fails Klarna will respond with a 4xx or 5xx status code together with a response body containing an error object with the error code, an array of error messages and a unique error id to be used to identify the request. Build your error-handling logic on the HTTP status code together with the error_code.

Parameter	Definition
`error_id`	A unique identifier for the request generated by Klarna. This ID supports investigations when Partners need help from Klarna's support team.
`error_code`	Error code for further categorizing the error. Klarna recommends using this error code for building error handling logic.
`error_message`	A human readable error message. The error message is not meant to be displayable to customers shopping, but to assist in technical troubleshooting.
`validation_errors`	For `VALIDATION_ERROR`, an array of `{ parameter, reason, doc_url }` objects describing each parameter that failed validation.
`doc_url`	Link to Klarna docs describing how to use the API to avoid the error, or a more detailed explanation of why the error occurred. To be provided when available.

Example of an API response with error details:

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.
`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...