Skip to main content

Error Codes Reference

Complete reference of all HTTP status codes and error responses.

Complete reference of all error codes returned by Paysera Checkout APIs.

HTTP Status Codes​

CodeNameRetryDescription
200OK-Request successful
201Created-Resource created successfully
400Bad RequestNoMalformed request syntax
401UnauthorizedMaybe*Authentication failed
403ForbiddenNoInsufficient permissions
404Not FoundNoResource does not exist
409ConflictNoResource conflict (e.g., duplicate)
422Unprocessable EntityNoValidation error
429Too Many RequestsYesRate limit exceeded
500Internal Server ErrorYesServer-side error
502Bad GatewayYesUpstream service error
503Service UnavailableYesService temporarily unavailable

*Retry after refreshing access token

Error Response Format​

Most errors use the simple envelope:

{
"error": "error_code",
"error_description": "Human-readable description"
}

Validation errors include per-field details under error_properties (a map of field path → list of message strings):

{
"error": "invalid_properties",
"error_description": "Validation failed",
"error_properties": {
"purchase.amount": ["Amount should be greater than 0"],
"purchase.currency": ["Currency is required"]
}
}

Authentication Errors​

Error CodeHTTP StatusMessageSolution
invalid_client401Invalid client credentialsVerify client_id and client_secret
invalid_token401Token is expiredRequest new access token
invalid_token401Token validation failedCheck token format and environment
invalid_grant401Invalid grant typeUse client_credentials grant
unauthorized401Authorization requiredInclude Authorization header

Validation Errors​

Error CodeHTTP StatusCommon FieldsDescription
invalid_properties400VariousOne or more fields failed validation. Per-field details are returned in error_properties.
validation_payment_method_required400payment_details.key, preferred_payment_method_keyPayment Link, Update Payment Link: the direct_payment flow needs a payment method. Send payment_details.key (create) or preferred_payment_method_key (update) with the direct_payment flow.

Common Field Errors​

FieldError MessageSolution
project_idProject is requiredInclude project_id in request or ensure your JWT token contains a project
project_idProject not foundVerify project ID exists and you have access
purchase.amountAmount must be greater than 0Use positive amount in minor units
purchase.amountInvalid amount formatUse a whole number in minor units (e.g., 1000 for €10.00)
purchase.currencyCurrency is requiredInclude currency code
purchase.currencyInvalid currencyUse valid ISO 4217 code
purchase.referenceReference is requiredInclude a reference (it does not need to be unique)
redirect_urls.success_urlInvalid URL formatUse valid HTTPS URL
redirect_urls.callback_urlInvalid URL formatUse valid HTTPS URL
lifetimeLifetime must be positiveUse a positive integer, or 0 to never expire. Split orders require 0.
experience.languageInvalid language codeUse supported language

Resource Errors​

Error CodeHTTP StatusMessageDescription
not_found404Order not foundOrder ID does not exist
not_found404Payment link not foundLink ID does not exist
not_found404Project not foundProject ID does not exist

Business Logic Errors​

Error CodeHTTP StatusMessageSolution
conflict409Order already completedOrder cannot be modified

Split Payment Errors​

Returned by order creation and payment-link creation when the request conflicts with the project's split policy. Request-validation problems return 400; policy, beneficiary, and override conflicts return 422. Some codes add details under error_properties.

Setup and request validation:

Error CodeHTTP StatusEndpointSolution
intermediary_account_required400OrderThe project's split setup is not complete — request activation through Paysera support
invalid_properties400OrderRequest validation failed (e.g. splits[].type must be variadic/tip; split_overrides.slots[].type must be fixed/percentage/remainder); fix the fields in error_properties
validation_split_expiration_not_allowed400Payment LinkSet lifetime: 0 — split-enabled orders need non-expiring links
validation_split_amount_mismatch400Payment LinkSet the link amount equal to the split order's full amount
policy_not_configured422OrderThe project owner needs to finish configuring the policy template
policy_invalid422OrderThe project's split policy is invalid — contact Paysera support

Standard splits (splits[]):

Error CodeHTTP StatusEndpointSolution
variadic_entry_required422OrderAdd a {type:"variadic", beneficiary_id:"..."} entry
variadic_entry_not_allowed422OrderRemove the variadic entry — the policy has no variadic slot
variadic_entry_requires_policy422OrderOnly send variadic entries when the project has a configured policy
split_variadic_count_mismatch422OrderSend exactly one variadic entry per variadic slot (error_properties.expected/actual)
split_variadic_slot_id_required422OrderMultiple variadic slots — set slot_id on each variadic entry (error_properties.entry_indexes)
split_variadic_slot_id_unknown422OrderA variadic slot_id matches no variadic slot (error_properties.slot_ids)
split_variadic_slot_id_duplicate422OrderUse each variadic slot_id at most once (error_properties.slot_ids)
variadic_beneficiary_required422OrderSet beneficiary_id or an inline beneficiary on the variadic entry
tip_beneficiary_required422OrderSet beneficiary_id or an inline beneficiary on the tip entry
split_entry_identifier_invalid422OrderSet either beneficiary_id or beneficiary on a split entry, not both
tip_entries_without_tips_enabled422OrderPayer tips through Split Payments are not enabled on the project: have them enabled, or drop the tip entries. Not related to tips_enabled
tip_beneficiary_consent_not_given422OrderThe tip recipient has a payout account but no tax-agent consent, e.g. withdrew it (LT projects) (error_properties.recipient_name). A recipient with no payout account yet gets split_beneficiary_not_found instead
inline_beneficiary_not_allowed_for_tip422OrderRegister tip recipients up front (e.g. by phone) on projects under the tax-agent consent regime
inline_beneficiary_rejected422OrderThe inline beneficiary was refused registration — the stable reason key is in error_properties.rule
split_amount_too_low422OrderIncrease the order amount to meet the policy's minimum. Also returned by PATCH order when a lowered amount no longer covers the split rules

Per-order overrides (split_overrides):

Error CodeHTTP StatusEndpointSolution
overrides_not_enabled422OrderRequest the per-order overrides capability (Paysera support)
split_overrides_require_policy422OrderOnly use overrides when the project has a configured policy
split_overrides_incomplete422OrderRestate every policy slot exactly once; with variable split recipients a variadic slot may be omitted (error_properties.missing_slot_ids)
split_override_unknown_slot422OrderUse slot_ids from the split-policy response (error_properties.slot_ids)
split_override_duplicate_slot422OrderList each slot once — with variable split recipients, only merchant/beneficiary slots must be unique (error_properties.slot_ids)
split_override_duplicate_recipient422OrderVariable split recipients only: name each recipient once per order (error_properties.recipients)
split_override_recipient_required422OrderAdd a recipient to the variadic slot (error_properties.slot_id)
split_override_recipient_not_allowed422OrderOmit recipient for the merchant slot (error_properties.slot_id)
split_override_recipient_invalid422OrderProvide exactly one of beneficiary_id/account/beneficiary (error_properties.slot_id)
split_override_recipient_ambiguous422OrderThe recipient sets more than one of beneficiary_id/account/beneficiary — keep exactly one (error_properties.slot_id)
split_override_account_not_resolvable422Orderaccount is not a Paysera account — use an inline beneficiary or a registered beneficiary_id (error_properties.slot_id, account)
split_override_value_invalid422Orderfixed > 0; percentage 1–10000; omit for remainder (error_properties.slot_id, type)
split_override_variadic_entry_not_allowed422OrderPut only tip entries in splits when using overrides
split_remainder_required422OrderMake exactly one slot remainder
split_too_many_remainders422OrderUse exactly one remainder slot
split_percentage_sum_exceeded422OrderKeep percentage slots below 100% in total

Recipient resolution (both paths):

Error CodeHTTP StatusEndpointSolution
split_beneficiary_not_found422OrderRegister the beneficiary, then reference its id (error_properties.beneficiary_ids). On LT projects, also returned for a tip recipient who has not given tax-agent consent yet. The error looks the same, so check the beneficiary list: consent_status: not_given with account_number: null means the recipient is registered. Wait until they consent — registering them again returns 409 conflict
split_beneficiary_account_not_found422OrderUse an existing Paysera EVP account (error_properties.missing_accounts)
splits_invalid422OrderReview the split entries against the project's policy

Held-payout resolution — returned by the Verification of Payee resolution endpoints:

Error CodeHTTP StatusEndpointSolution
vop_confirmation_superseded409ConfirmThe recipient changed since the webhook you are answering — review the latest pair before confirming
vop_mismatch_not_confirmable422ConfirmThe leg is not awaiting a name-check confirmation — nothing to confirm
vop_beneficiary_not_correctable422CorrectThe leg is not held on a name mismatch, or is already at the bank
vop_beneficiary_iban_invalid422CorrectThe corrected IBAN is not a valid IBAN — check its structure and checksum
vop_beneficiary_iban_not_eea422CorrectThe corrected IBAN belongs to a country outside the European Economic Area — send an EEA IBAN
distribution_retry_unavailable503BothThe release could not be scheduled — retry later

Held-payout account correction — returned by Correct the Account of a Held Payout:

Error CodeHTTP StatusSolution
held_account_correction_superseded409The leg moved to another account since you read it — re-read the payment and send the account it pays now
held_account_unusable422The IBAN sent does not resolve to a usable Paysera account — check it, or use another account
held_account_not_correctable422The leg is not waiting on an unusable account — settled, failed, held for another reason, or paying a bank outside Paysera
tip_not_correctable422A tip leg: the recipient chose that account, so only Paysera support can move it
account_owner_changed422The account belongs to another Paysera user, or its owner could not be confirmed — the one code here that a later retry may pass
distribution_retry_unavailable503The correction could not be scheduled; the new account may already be recorded — re-read the payment before retrying

Returned payout re-send — returned by Re-send a Returned Payout:

Error CodeHTTP StatusSolution
payout_not_resendable422The leg does not belong to this payment, is not a returned payout, or its returned amount could not be established. If the earlier re-send was itself returned, answer the newer return instead (a repeated call for the same return is not refused — it answers ALREADY_RESENT). A return whose reason code is not self-service (AC01, AC04, AC06, RR03) is handled by Paysera customer support
distribution_retry_unavailable503The re-send could not be created — retry later

Payer-Set Amount and Tip Errors​

Returned when the payer sets the amount or the order offers a tip. Order creation returns them as 422, payment-link creation as 400, both in the simple envelope (error and error_description, no error_properties).

Error CodeHTTP StatusEndpointSolution
payer_set_amount_not_enabled422OrderSwitch on Payer-set amount on the project's Features page in the merchant dashboard
payer_set_amount_with_split_payments422OrderPayer-set amount is not available on a project with split payments, or on an order with splits / split_overrides
payer_set_amount_with_amount422 / 400Order, Payment LinkOmit purchase.amount when the payer sets the amount
payer_set_amount_limits_without_flag422OrderSend minimum_amount / maximum_amount only with payer_sets_amount: true
minimum_amount_below_floor422OrderSet minimum_amount to at least 1
maximum_amount_above_platform_maximum422OrderSet maximum_amount to at most 1000000
minimum_amount_not_below_maximum422OrderMake the minimum lower than the maximum (an omitted limit counts as 1 or 1000000)
suggested_amount_without_payer_set422 / 400Order, Payment LinkSend suggested_amount only for a payer-set order
suggested_amount_out_of_limits422 / 400Order, Payment LinkKeep suggested_amount within the minimum and maximum
amount_buttons_without_payer_set422 / 400Order, Payment LinkSend amount_buttons only for a payer-set order
amount_buttons_count422 / 400Order, Payment LinkSend three or four amount buttons
amount_buttons_not_ascending422 / 400Order, Payment LinkMake the amount buttons unique and strictly ascending
amount_buttons_out_of_limits422 / 400Order, Payment LinkKeep each amount button within the minimum and maximum
validation_direct_payment_with_payer_set_amount400Payment LinkUse the default paysera_checkout flow; direct_payment is not available for a payer-set order
validation_direct_payment_with_tips400Payment LinkUse the default paysera_checkout flow; direct_payment is not available for an order with tips_enabled: true
validation_direct_payment_with_tip_rule400Payment LinkUse the default paysera_checkout flow; direct_payment is not available for an order with a tip split
payer_set_amount_not_editable422 / 400Update Order, Update Payment LinkA payer-set order's amount and currency cannot be changed, and a payer-set link cannot be updated
tips_and_payer_set_amount_conflict422OrderDo not combine tips_enabled with purchase.payer_sets_amount
tips_not_enabled422OrderSwitch on Tips on the project's Features page in the merchant dashboard
tips_with_split_payments422OrderTips are not available on a project with split payments; drop tips_enabled, or route tips through Split Payments
tips_and_tokenization_conflict422OrderDo not combine tips_enabled with tokenization

Rate Limiting Errors​

Rate limiting is enforced at the API gateway. On throttle, the gateway returns 429 Too Many Requests with a Retry-After header indicating the number of seconds to wait before retrying.

HeaderDescription
Retry-AfterSeconds to wait before retry

Rate Limit Handling Examples​

Implement exponential backoff when encountering rate limits:

<?php

class RateLimitHandler
{
private int $maxRetries = 3;
private int $baseDelay = 1000; // milliseconds

public function executeWithRetry(callable $request): mixed
{
$attempt = 0;

while ($attempt < $this->maxRetries) {
try {
return $request();
} catch (RateLimitException $e) {
$attempt++;

if ($attempt >= $this->maxRetries) {
throw $e;
}

$delay = $this->calculateDelay($attempt, $e->getRetryAfter());
usleep($delay * 1000);
}
}
}

private function calculateDelay(int $attempt, ?int $retryAfter): int
{
if ($retryAfter !== null) {
return $retryAfter * 1000; // Convert seconds to milliseconds
}

// Exponential backoff: 1s, 2s, 4s...
return $this->baseDelay * pow(2, $attempt - 1);
}
}

// Usage
$handler = new RateLimitHandler();
$result = $handler->executeWithRetry(function() use ($client, $payload) {
return $client->createOrder($payload);
});

Server Errors​

HTTP StatusDescriptionSolution
500Internal server errorRetry with backoff
502Bad gateway (upstream service unreachable)Retry with backoff
503Service temporarily unavailableRetry with backoff

Server-side errors return the simple envelope (error, error_description).

Order creation returns 503 merchant_project_unavailable when the project's settings could not be loaded. The problem is temporary — retry with backoff.

Error Handling by Type​

PHP Example​

<?php

function handleError(int $httpCode, array $body): never
{
$error = $body['error'] ?? 'unknown_error';
$description = $body['error_description'] ?? 'Unknown error';
$properties = $body['error_properties'] ?? [];

match (true) {
$httpCode === 401 => throw new AuthenticationException($description),
$httpCode === 403 => throw new AuthorizationException($description),
$httpCode === 404 => throw new NotFoundException($description),
$httpCode === 409 => throw new ConflictException($description),
$httpCode === 400 => throw new ValidationException($description, $properties),
$httpCode === 429 => throw new RateLimitException($description),
default => throw new ApiException($description, $httpCode),
};
}

JavaScript Example​

function handleError(response, body) {
const { error, error_description, error_properties } = body;

switch (response.status) {
case 401:
throw new AuthenticationError(error_description);
case 403:
throw new AuthorizationError(error_description);
case 404:
throw new NotFoundError(error_description);
case 409:
throw new ConflictError(error_description);
case 400:
throw new ValidationError(error_description, error_properties);
case 429:
throw new RateLimitError(error_description, response.headers.get('Retry-After'));
default:
throw new ApiError(error_description, response.status);
}
}

User-Friendly Messages​

Error CodeUser Message
invalid_clientUnable to authenticate. Please contact support.
invalid_tokenSession expired. Please try again.
invalid_propertiesPlease check your input and try again.
not_foundThe requested item was not found.
conflictThis action cannot be completed. The item may already exist.
429 Too Many RequestsToo many requests. Please wait a moment.
500/502/503Service temporarily unavailable. Please try again.

Troubleshooting Guide​

SymptomCheckSolution
401 on all requestsCredentialsVerify client_id/secret
401 after workingTokenRefresh access token
400 with amountFormatUse minor units as an integer (e.g., 1000 for €10.00)
400 with URLProtocolUse HTTPS URLs
404 on orderIDVerify order UUID
409 on payment-link createDuplicate link nameUse a unique link name per order
429 frequentlyRequest rateImplement rate limiting