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

Code	Name	Retry	Description
200	OK	-	Request successful
201	Created	-	Resource created successfully
400	Bad Request	No	Malformed request syntax
401	Unauthorized	Maybe*	Authentication failed
403	Forbidden	No	Insufficient permissions
404	Not Found	No	Resource does not exist
409	Conflict	No	Resource conflict (e.g., duplicate)
422	Unprocessable Entity	No	Validation error
429	Too Many Requests	Yes	Rate limit exceeded
500	Internal Server Error	Yes	Server-side error
502	Bad Gateway	Yes	Upstream service error
503	Service Unavailable	Yes	Service 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 Code	HTTP Status	Message	Solution
`invalid_client`	401	Invalid client credentials	Verify client_id and client_secret
`invalid_token`	401	Token is expired	Request new access token
`invalid_token`	401	Token validation failed	Check token format and environment
`invalid_grant`	401	Invalid grant type	Use `client_credentials` grant
`unauthorized`	401	Authorization required	Include Authorization header

Validation Errors

Error Code	HTTP Status	Common Fields	Description
`invalid_properties`	400	Various	One or more fields failed validation. Per-field details are returned in `error_properties`.

Common Field Errors

Field	Error Message	Solution
`project_id`	Project is required	Include `project_id` in request or ensure your JWT token contains a project
`project_id`	Project not found	Verify project ID exists and you have access
`purchase.amount`	Amount must be greater than 0	Use positive amount in minor units
`purchase.amount`	Invalid amount format	Use a whole number in minor units (e.g., `1000` for €10.00)
`purchase.currency`	Currency is required	Include currency code
`purchase.currency`	Invalid currency	Use valid ISO 4217 code
`purchase.reference`	Reference is required	Include a reference (it does not need to be unique)
`redirect_urls.success_url`	Invalid URL format	Use valid HTTPS URL
`redirect_urls.callback_url`	Invalid URL format	Use valid HTTPS URL
`lifetime`	Lifetime must be positive	Use a positive integer, or `0` to never expire. Split orders require `0`.
`experience.language`	Invalid language code	Use supported language

Resource Errors

Error Code	HTTP Status	Message	Description
`not_found`	404	Order not found	Order ID does not exist
`not_found`	404	Payment link not found	Link ID does not exist
`not_found`	404	Project not found	Project ID does not exist

Business Logic Errors

Error Code	HTTP Status	Message	Solution
`conflict`	409	Order already completed	Order 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 Code	HTTP Status	Endpoint	Solution
`intermediary_account_required`	400	Order	The project's split setup is not complete — request activation through Paysera support
`invalid_properties`	400	Order	Request 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_allowed`	400	Payment Link	Set `lifetime: 0` — split-enabled orders need non-expiring links
`validation_split_amount_mismatch`	400	Payment Link	Set the link amount equal to the split order's full amount
`policy_not_configured`	422	Order	The project owner needs to finish configuring the policy template
`policy_invalid`	422	Order	The project's split policy is invalid — contact Paysera support

Standard splits (splits[]):

Error Code	HTTP Status	Endpoint	Solution
`variadic_entry_required`	422	Order	Add a `{type:"variadic", beneficiary_id:"..."}` entry
`variadic_entry_not_allowed`	422	Order	Remove the variadic entry — the policy has no variadic slot
`variadic_entry_requires_policy`	422	Order	Only send variadic entries when the project has a configured policy
`split_variadic_count_mismatch`	422	Order	Send exactly one variadic entry per variadic slot (`error_properties.expected`/`actual`)
`split_variadic_slot_id_required`	422	Order	Multiple variadic slots — set `slot_id` on each variadic entry (`error_properties.entry_indexes`)
`split_variadic_slot_id_unknown`	422	Order	A variadic `slot_id` matches no variadic slot (`error_properties.slot_ids`)
`split_variadic_slot_id_duplicate`	422	Order	Use each variadic `slot_id` at most once (`error_properties.slot_ids`)
`variadic_beneficiary_required`	422	Order	Set `beneficiary_id` on the variadic entry
`tip_beneficiary_required`	422	Order	Set `beneficiary_id` on the tip entry
`tip_entries_without_tips_enabled`	422	Order	Have payer tips enabled, or drop the tip entries
`tip_beneficiary_consent_not_given`	422	Order	Tip recipient must give tax-agent consent (LT projects) (`error_properties.recipient_name`)
`split_amount_too_low`	422	Order	Increase the order amount to meet the policy's minimum

Per-order overrides (split_overrides):

Error Code	HTTP Status	Endpoint	Solution
`overrides_not_enabled`	422	Order	Request the per-order overrides capability (Paysera support)
`split_overrides_require_policy`	422	Order	Only use overrides when the project has a configured policy
`split_overrides_incomplete`	422	Order	Restate every policy slot exactly once (`error_properties.missing_slot_ids`)
`split_override_unknown_slot`	422	Order	Use `slot_id`s from the split-policy response (`error_properties.slot_ids`)
`split_override_duplicate_slot`	422	Order	List each slot once (`error_properties.slot_ids`)
`split_override_recipient_required`	422	Order	Add a `recipient` to the variadic slot (`error_properties.slot_id`)
`split_override_recipient_not_allowed`	422	Order	Omit `recipient` for the merchant slot (`error_properties.slot_id`)
`split_override_recipient_invalid`	422	Order	Provide exactly one of `beneficiary_id`/`account` (`error_properties.slot_id`)
`split_override_value_invalid`	422	Order	`fixed` > 0; `percentage` 1–10000; omit for `remainder` (`error_properties.slot_id`, `type`)
`split_override_variadic_entry_not_allowed`	422	Order	Put only tip entries in `splits` when using overrides
`split_remainder_required`	422	Order	Make exactly one slot `remainder`
`split_too_many_remainders`	422	Order	Use exactly one `remainder` slot
`split_percentage_sum_exceeded`	422	Order	Keep percentage slots below 100% in total

Recipient resolution (both paths):

Error Code	HTTP Status	Endpoint	Solution
`split_beneficiary_not_found`	422	Order	Register the beneficiary, then reference its id (`error_properties.beneficiary_ids`)
`split_beneficiary_account_not_found`	422	Order	Use an existing Paysera EVP account (`error_properties.missing_accounts`)
`splits_invalid`	422	Order	Review the split entries against the project's policy

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.

Header	Description
`Retry-After`	Seconds to wait before retry

Rate Limit Handling Examples

Implement exponential backoff when encountering rate limits:

PHP
JavaScript
Python

<?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);
});

class RateLimitHandler {
  constructor(maxRetries = 3, baseDelay = 1000) {
    this.maxRetries = maxRetries;
    this.baseDelay = baseDelay;
  }

  async executeWithRetry(request) {
    let attempt = 0;

    while (attempt < this.maxRetries) {
      try {
        return await request();
      } catch (error) {
        if (error.status !== 429) {
          throw error;
        }

        attempt++;

        if (attempt >= this.maxRetries) {
          throw error;
        }

        const retryAfter = error.headers?.get('Retry-After');
        const delay = this.calculateDelay(attempt, retryAfter);
        await this.sleep(delay);
      }
    }
  }

  calculateDelay(attempt, retryAfter) {
    if (retryAfter) {
      return parseInt(retryAfter, 10) * 1000;
    }
    return this.baseDelay * Math.pow(2, attempt - 1);
  }

  sleep(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

// Usage
const handler = new RateLimitHandler();
const result = await handler.executeWithRetry(() => createOrder(payload));

import time
from typing import Callable, TypeVar

T = TypeVar('T')

class RateLimitHandler:
    def __init__(self, max_retries: int = 3, base_delay: float = 1.0):
        self.max_retries = max_retries
        self.base_delay = base_delay

    def execute_with_retry(self, request: Callable[[], T]) -> T:
        attempt = 0

        while attempt < self.max_retries:
            try:
                return request()
            except RateLimitError as e:
                attempt += 1

                if attempt >= self.max_retries:
                    raise

                delay = self._calculate_delay(attempt, e.retry_after)
                time.sleep(delay)

    def _calculate_delay(self, attempt: int, retry_after: int | None) -> float:
        if retry_after is not None:
            return float(retry_after)
        return self.base_delay * (2 ** (attempt - 1))

# Usage
handler = RateLimitHandler()
result = handler.execute_with_retry(lambda: create_order(payload))

Server Errors

HTTP Status	Description	Solution
500	Internal server error	Retry with backoff
502	Bad gateway (upstream service unreachable)	Retry with backoff
503	Service temporarily unavailable	Retry with backoff

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

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 Code	User Message
`invalid_client`	Unable to authenticate. Please contact support.
`invalid_token`	Session expired. Please try again.
`invalid_properties`	Please check your input and try again.
`not_found`	The requested item was not found.
`conflict`	This action cannot be completed. The item may already exist.
`429 Too Many Requests`	Too many requests. Please wait a moment.
`500/502/503`	Service temporarily unavailable. Please try again.

Troubleshooting Guide

Symptom	Check	Solution
401 on all requests	Credentials	Verify client_id/secret
401 after working	Token	Refresh access token
400 with amount	Format	Use minor units as an integer (e.g., `1000` for €10.00)
400 with URL	Protocol	Use HTTPS URLs
404 on order	ID	Verify order UUID
409 on payment-link create	Duplicate link name	Use a unique link name per order
429 frequently	Request rate	Implement rate limiting

HTTP Status Codes​

Error Response Format​

Authentication Errors​

Validation Errors​

Common Field Errors​

Resource Errors​

Business Logic Errors​

Split Payment Errors​

Rate Limiting Errors​

Rate Limit Handling Examples​

Server Errors​

Error Handling by Type​

PHP Example​

JavaScript Example​

User-Friendly Messages​

Troubleshooting Guide​