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.

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