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.

6 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.
`FRAMEWORK_CHANGE_NOT_ALLOWED`	409	The dispute framework of the Payment Account can no longer be changed.	Do not retry unchanged. Contact your Klarna representative if the Payment Account needs a different framework.
`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`.
`UCP_IDEMPOTENCY_CONFLICT`	409	The seller already received this `Idempotency-Key` with a different request body. The seller returns this error and Klarna relays it unchanged, so the `code` and `content` are the seller's.	Send a new `Idempotency-Key` for a new request, or resend the original body unchanged to retry the original one.
`UCP_INTERNAL_ERROR`	500	The request failed for an unexpected internal reason.	Retry after a short delay. If the error persists, contact Klarna support with the `Request-Id` you sent.
`UCP_INVALID_REQUEST`	400	The request failed before the operation ran: `Request-Id` is missing or is not a UUID, `Idempotency-Key` is missing or is not a UUID on a checkout operation that requires it, or `UCP-Agent` is missing or its profile URL could not be parsed. The response `code` is `invalid_request_id`, `invalid_idempotency_key`, or `invalid_profile_url`. On checkout, the seller can also reject the request with this status, and Klarna relays its error unchanged.	Fix the named input and retry. For `invalid_request_id`, send a UUID `Request-Id`. For `invalid_idempotency_key`, send a UUID `Idempotency-Key`. For `invalid_profile_url`, send a `UCP-Agent` header whose profile URL is `https:` on a public domain name, with the default port and no credentials.
`UCP_PROFILE_UNREACHABLE`	424	The agent profile URL in the `UCP-Agent` header could not be fetched. On checkout, the seller fetches the profile, and Klarna relays its error unchanged.	Confirm the profile is publicly served over `https:` at the advertised URL, then retry.
`UCP_UNPROCESSABLE_PROFILE`	422	The agent profile was fetched but could not be used: it is malformed, or it declares a UCP protocol version that is not supported. On checkout, the seller fetches the profile, and Klarna relays its error unchanged.	Correct the profile document at the advertised URL, or declare a supported UCP protocol version, then retry.
`UCP_UPSTREAM_FAILURE`	502	A system Klarna depends on to serve the catalog or relay the checkout failed.	Retry after a short delay. If the error persists, contact Klarna support with the `Request-Id` you sent.
`UCP_UPSTREAM_TIMEOUT`	504	A system Klarna depends on to serve the catalog or relay the checkout did not respond in time.	Retry using the same backoff as for rate-limited requests. If the error persists, contact Klarna support with the `Request-Id` you sent.
`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...