Error Handling

Best practices for handling errors and edge cases in your integration.

This guide covers error handling strategies for Paysera Checkout integrations.

Error Response Format

All API errors return a consistent JSON structure:

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

Field-validation errors additionally include error_properties — a map of field path → list of message strings:

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

Match on the machine-readable error code, not on error_description (which may change or be localized).

HTTP Status Codes

Code	Meaning	Retry
200	Success	N/A
201	Created	N/A
400	Bad Request / field validation (invalid_properties)	No
401	Unauthorized	Maybe*
403	Forbidden	No
404	Not Found	No
409	Conflict	No
422	Business-rule validation	No
429	Rate Limited	Yes (with backoff)
500	Server Error	Yes (with backoff)
502	Bad Gateway	Yes (with backoff)
503	Service Unavailable	Yes (with backoff)

*Retry after refreshing access token

Common Errors

Authentication Errors

Invalid Credentials (401)

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials"
}

Solution: Verify client_id and client_secret are correct.

Expired Token (401)

{
  "error": "invalid_token",
  "error_description": "Token is expired"
}

Solution: Request a new access token.

Invalid Token (401)

{
  "error": "invalid_token",
  "error_description": "Token validation failed"
}

Solution: Check token format and ensure you're using the correct environment.

Field Validation (400)

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

Solution: Fix the fields listed in error_properties and retry. Each key is a field path; each value is a list of messages for that field.

Business-rule Validation (422)

Some requests are well-formed but violate a business rule — for example a split request that conflicts with the project's policy. These return 422 with a specific error code (and sometimes error_properties):

{
  "error": "variadic_entry_required",
  "error_description": "The configured split policy requires exactly one variadic entry."
}

Solution: Handle by error code. See Error Codes for the full catalog (including all split-payment codes).

Not Found (404)

{
  "error": "not_found",
  "error_description": "Order not found"
}

Solution: Verify the resource ID is correct.

Conflict (409)

{
  "error": "conflict",
  "error_description": "Order already completed"
}

Solution: The resource is in a state that doesn't allow the operation (for example, modifying an already-completed order). Note that order reference is not required to be unique — a duplicate reference does not cause a conflict.

Rate Limited (429)

{
  "error": "rate_limited",
  "error_description": "Too many requests"
}

Response Headers:

Retry-After: 60
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705320000

Solution: Implement exponential backoff and respect Retry-After header.

Error Handling Code Examples

Each sample reads error_description for the human-readable message and, on a 400, iterates the error_properties map (field → list of messages).

PHP

<?php

class PayseraClient
{
    private string $baseUrl;
    private ?string $accessToken = null;

    public function request(string $method, string $endpoint, array $data = []): array
    {
        $maxRetries = 3;
        $attempt = 0;

        while ($attempt < $maxRetries) {
            try {
                return $this->doRequest($method, $endpoint, $data);
            } catch (RateLimitException $e) {
                $retryAfter = $e->getRetryAfter();
                sleep($retryAfter);
                $attempt++;
            } catch (TokenExpiredException $e) {
                $this->refreshToken();
                $attempt++;
            } catch (ServerException $e) {
                // Exponential backoff
                sleep(pow(2, $attempt));
                $attempt++;
            }
        }

        throw new MaxRetriesExceededException();
    }

    private function doRequest(string $method, string $endpoint, array $data): array
    {
        $ch = curl_init($this->baseUrl . $endpoint);

        curl_setopt_array($ch, [
            CURLOPT_CUSTOMREQUEST => $method,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER => [
                'Authorization: Bearer ' . $this->accessToken,
                'Content-Type: application/json',
            ],
            CURLOPT_POSTFIELDS => $method !== 'GET' ? json_encode($data) : null,
        ]);

        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        $body = json_decode($response, true);
        $description = $body['error_description'] ?? ($body['error'] ?? 'Unknown error');

        return match (true) {
            $httpCode >= 200 && $httpCode < 300 => $body,
            $httpCode === 401 => throw new TokenExpiredException($description),
            $httpCode === 400 => throw new ValidationException($description, $body['error_properties'] ?? []),
            $httpCode === 429 => throw new RateLimitException($description),
            $httpCode >= 500 => throw new ServerException($description),
            default => throw new ApiException($description, $httpCode),
        };
    }
}

// Usage with error handling
try {
    $order = $client->request('POST', '/merchant-order/integration/v1/orders', [
        'purchase' => ['reference' => 'ORDER-123', 'amount' => 2500, 'currency' => 'EUR'],
    ]);
} catch (ValidationException $e) {
    foreach ($e->getProperties() as $field => $messages) {
        foreach ($messages as $message) {
            echo "Error in {$field}: {$message}\n";
        }
    }
} catch (ApiException $e) {
    error_log("API error: " . $e->getMessage());
}

JavaScript

class PayseraClient {
  constructor(baseUrl) {
    this.baseUrl = baseUrl;
    this.accessToken = null;
  }

  async request(method, endpoint, data = null) {
    const maxRetries = 3;
    let attempt = 0;

    while (attempt < maxRetries) {
      try {
        return await this.doRequest(method, endpoint, data);
      } catch (error) {
        if (error instanceof RateLimitError) {
          await this.sleep(error.retryAfter * 1000);
          attempt++;
        } else if (error instanceof TokenExpiredError) {
          await this.refreshToken();
          attempt++;
        } else if (error instanceof ServerError) {
          await this.sleep(Math.pow(2, attempt) * 1000);
          attempt++;
        } else {
          throw error;
        }
      }
    }

    throw new MaxRetriesError();
  }

  async doRequest(method, endpoint, data) {
    const response = await fetch(this.baseUrl + endpoint, {
      method,
      headers: {
        'Authorization': `Bearer ${this.accessToken}`,
        'Content-Type': 'application/json',
      },
      body: data ? JSON.stringify(data) : undefined,
    });

    const body = await response.json();

    if (response.ok) {
      return body;
    }

    const description = body.error_description || body.error || 'Unknown error';

    switch (response.status) {
      case 401:
        throw new TokenExpiredError(description);
      case 400:
        throw new ValidationError(description, body.error_properties || {});
      case 429:
        throw new RateLimitError(description, response.headers.get('Retry-After'));
      default:
        if (response.status >= 500) {
          throw new ServerError(description);
        }
        throw new ApiError(description, response.status);
    }
  }

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

// Usage
try {
  const order = await client.request('POST', '/merchant-order/integration/v1/orders', {
    purchase: { reference: 'ORDER-123', amount: 2500, currency: 'EUR' },
  });
} catch (error) {
  if (error instanceof ValidationError) {
    Object.entries(error.properties).forEach(([field, messages]) => {
      messages.forEach(message => console.error(`Error in ${field}: ${message}`));
    });
  } else {
    console.error('API error:', error.message);
  }
}

Python

import time
import requests
from typing import Optional, Dict, Any

class PayseraClient:
    def __init__(self, base_url: str):
        self.base_url = base_url
        self.access_token: Optional[str] = None

    def request(self, method: str, endpoint: str, data: Optional[Dict] = None) -> Dict[str, Any]:
        max_retries = 3
        attempt = 0

        while attempt < max_retries:
            try:
                return self._do_request(method, endpoint, data)
            except RateLimitError as e:
                time.sleep(e.retry_after)
                attempt += 1
            except TokenExpiredError:
                self._refresh_token()
                attempt += 1
            except ServerError:
                time.sleep(2 ** attempt)
                attempt += 1

        raise MaxRetriesError()

    def _do_request(self, method: str, endpoint: str, data: Optional[Dict]) -> Dict[str, Any]:
        response = requests.request(
            method,
            self.base_url + endpoint,
            headers={
                'Authorization': f'Bearer {self.access_token}',
                'Content-Type': 'application/json',
            },
            json=data,
        )

        body = response.json()

        if response.ok:
            return body

        description = body.get('error_description') or body.get('error', 'Unknown error')

        if response.status_code == 401:
            raise TokenExpiredError(description)
        elif response.status_code == 400:
            raise ValidationError(description, body.get('error_properties', {}))
        elif response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            raise RateLimitError(description, retry_after)
        elif response.status_code >= 500:
            raise ServerError(description)
        else:
            raise ApiError(description, response.status_code)

# Usage
try:
    order = client.request('POST', '/merchant-order/integration/v1/orders', {
        'purchase': {'reference': 'ORDER-123', 'amount': 2500, 'currency': 'EUR'},
    })
except ValidationError as e:
    for field, messages in e.properties.items():
        for message in messages:
            print(f"Error in {field}: {message}")
except ApiError as e:
    print(f"API error: {e.message}")

Kotlin

import java.net.URI
import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse
import kotlinx.serialization.json.*
import kotlin.math.pow

class PayseraClient(private val baseUrl: String) {
    private var accessToken: String? = null
    private val client = HttpClient.newHttpClient()

    suspend fun request(method: String, endpoint: String, data: JsonObject? = null): JsonObject {
        val maxRetries = 3
        var attempt = 0

        while (attempt < maxRetries) {
            try {
                return doRequest(method, endpoint, data)
            } catch (e: RateLimitException) {
                Thread.sleep(e.retryAfter * 1000L)
                attempt++
            } catch (e: TokenExpiredException) {
                refreshToken()
                attempt++
            } catch (e: ServerException) {
                Thread.sleep((2.0.pow(attempt) * 1000).toLong())
                attempt++
            }
        }

        throw MaxRetriesException()
    }

    private fun doRequest(method: String, endpoint: String, data: JsonObject?): JsonObject {
        val requestBuilder = HttpRequest.newBuilder()
            .uri(URI.create(baseUrl + endpoint))
            .header("Authorization", "Bearer $accessToken")
            .header("Content-Type", "application/json")

        when (method) {
            "GET" -> requestBuilder.GET()
            "POST" -> requestBuilder.POST(HttpRequest.BodyPublishers.ofString(data?.toString() ?: ""))
        }

        val response = client.send(requestBuilder.build(), HttpResponse.BodyHandlers.ofString())
        val body = Json.parseToJsonElement(response.body()).jsonObject
        val description = body["error_description"]?.jsonPrimitive?.content
            ?: body["error"]?.jsonPrimitive?.content ?: "Unknown error"

        return when {
            response.statusCode() in 200..299 -> body
            response.statusCode() == 401 -> throw TokenExpiredException(description)
            response.statusCode() == 400 -> throw ValidationException(description, body["error_properties"]?.jsonObject ?: buildJsonObject {})
            response.statusCode() == 429 -> throw RateLimitException(description)
            response.statusCode() >= 500 -> throw ServerException(description)
            else -> throw ApiException(description, response.statusCode())
        }
    }
}

// Usage
try {
    val order = client.request("POST", "/merchant-order/integration/v1/orders", buildJsonObject {
        putJsonObject("purchase") {
            put("reference", "ORDER-123")
            put("amount", 2500)
            put("currency", "EUR")
        }
    })
} catch (e: ValidationException) {
    e.properties.forEach { (field, messages) ->
        messages.jsonArray.forEach { message ->
            println("Error in $field: ${message.jsonPrimitive.content}")
        }
    }
} catch (e: ApiException) {
    println("API error: ${e.message}")
}

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "math"
    "net/http"
    "strconv"
    "time"
)

type PayseraClient struct {
    BaseURL     string
    AccessToken string
}

func (c *PayseraClient) Request(method, endpoint string, data interface{}) (map[string]interface{}, error) {
    maxRetries := 3
    attempt := 0

    for attempt < maxRetries {
        result, err := c.doRequest(method, endpoint, data)
        if err != nil {
            switch e := err.(type) {
            case *RateLimitError:
                time.Sleep(time.Duration(e.RetryAfter) * time.Second)
                attempt++
            case *TokenExpiredError:
                c.refreshToken()
                attempt++
            case *ServerError:
                time.Sleep(time.Duration(math.Pow(2, float64(attempt))) * time.Second)
                attempt++
            default:
                return nil, err
            }
        } else {
            return result, nil
        }
    }

    return nil, fmt.Errorf("max retries exceeded")
}

func (c *PayseraClient) doRequest(method, endpoint string, data interface{}) (map[string]interface{}, error) {
    var body io.Reader
    if data != nil {
        jsonData, _ := json.Marshal(data)
        body = bytes.NewBuffer(jsonData)
    }

    req, _ := http.NewRequest(method, c.BaseURL+endpoint, body)
    req.Header.Set("Authorization", "Bearer "+c.AccessToken)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    respBody, _ := io.ReadAll(resp.Body)
    var result map[string]interface{}
    json.Unmarshal(respBody, &result)

    description, _ := result["error_description"].(string)
    if description == "" {
        if code, ok := result["error"].(string); ok {
            description = code
        } else {
            description = "Unknown error"
        }
    }

    switch {
    case resp.StatusCode >= 200 && resp.StatusCode < 300:
        return result, nil
    case resp.StatusCode == 401:
        return nil, &TokenExpiredError{Message: description}
    case resp.StatusCode == 400:
        return nil, &ValidationError{Message: description, Properties: result["error_properties"]}
    case resp.StatusCode == 429:
        retryAfter, _ := strconv.Atoi(resp.Header.Get("Retry-After"))
        return nil, &RateLimitError{Message: description, RetryAfter: retryAfter}
    case resp.StatusCode >= 500:
        return nil, &ServerError{Message: description}
    default:
        return nil, &ApiError{Message: description, StatusCode: resp.StatusCode}
    }
}

// Usage
func main() {
    order, err := client.Request("POST", "/merchant-order/integration/v1/orders", map[string]interface{}{
        "purchase": map[string]interface{}{
            "reference": "ORDER-123",
            "amount":    2500,
            "currency":  "EUR",
        },
    })

    if err != nil {
        switch e := err.(type) {
        case *ValidationError:
            if props, ok := e.Properties.(map[string]interface{}); ok {
                for field, messages := range props {
                    for _, m := range messages.([]interface{}) {
                        fmt.Printf("Error in %s: %s\n", field, m)
                    }
                }
            }
        default:
            fmt.Printf("API error: %s\n", err.Error())
        }
    }
}

C#

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

public class PayseraClient
{
    private readonly string _baseUrl;
    private readonly HttpClient _httpClient;
    private string? _accessToken;

    public PayseraClient(string baseUrl)
    {
        _baseUrl = baseUrl;
        _httpClient = new HttpClient();
    }

    public async Task<JsonDocument> RequestAsync(string method, string endpoint, object? data = null)
    {
        const int maxRetries = 3;
        var attempt = 0;

        while (attempt < maxRetries)
        {
            try
            {
                return await DoRequestAsync(method, endpoint, data);
            }
            catch (RateLimitException e)
            {
                await Task.Delay(e.RetryAfter * 1000);
                attempt++;
            }
            catch (TokenExpiredException)
            {
                await RefreshTokenAsync();
                attempt++;
            }
            catch (ServerException)
            {
                await Task.Delay((int)Math.Pow(2, attempt) * 1000);
                attempt++;
            }
        }

        throw new MaxRetriesException();
    }

    private async Task<JsonDocument> DoRequestAsync(string method, string endpoint, object? data)
    {
        var request = new HttpRequestMessage(new HttpMethod(method), _baseUrl + endpoint);
        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", _accessToken);

        if (data != null)
        {
            var json = JsonSerializer.Serialize(data);
            request.Content = new StringContent(json, Encoding.UTF8, "application/json");
        }

        var response = await _httpClient.SendAsync(request);
        var body = await response.Content.ReadAsStringAsync();
        var doc = JsonDocument.Parse(body);

        if (response.IsSuccessStatusCode)
            return doc;

        var description = doc.RootElement.TryGetProperty("error_description", out var d)
            ? d.GetString() ?? ""
            : (doc.RootElement.TryGetProperty("error", out var c) ? c.GetString() ?? "" : "");

        return response.StatusCode switch
        {
            System.Net.HttpStatusCode.Unauthorized => throw new TokenExpiredException(description),
            System.Net.HttpStatusCode.BadRequest => throw new ValidationException(description, doc.RootElement),
            System.Net.HttpStatusCode.TooManyRequests => throw new RateLimitException(description, int.Parse(response.Headers.GetValues("Retry-After").First())),
            >= System.Net.HttpStatusCode.InternalServerError => throw new ServerException(description),
            _ => throw new ApiException(description, (int)response.StatusCode)
        };
    }
}

// Usage
try
{
    var order = await client.RequestAsync("POST", "/merchant-order/integration/v1/orders", new
    {
        purchase = new { reference = "ORDER-123", amount = 2500, currency = "EUR" }
    });
}
catch (ValidationException e)
{
    if (e.Body.TryGetProperty("error_properties", out var props))
    {
        foreach (var field in props.EnumerateObject())
        {
            foreach (var message in field.Value.EnumerateArray())
            {
                Console.WriteLine($"Error in {field.Name}: {message.GetString()}");
            }
        }
    }
}
catch (ApiException e)
{
    Console.WriteLine($"API error: {e.Message}");
}

Troubleshooting

Common Issues

Symptom	Possible Cause	Solution
401 on all requests	Wrong credentials	Verify client_id/secret
401 after working	Token expired	Implement token refresh
400 invalid_properties on valid data	Wrong field format	Check the field paths in error_properties
422 on a well-formed request	Business rule violated (e.g. split policy)	Handle by error code — see Error Codes
429 frequently	Too many requests	Implement rate limiting
500 errors	Server issue	Retry with backoff

Debug Checklist

1. Check credentials - Correct client_id and client_secret?
2. Check URL - Using correct API base URL?
3. Check token - Is token expired? Is it included in header?
4. Check request body - Is JSON valid? Are all required fields present?
5. Check amount format - Is it an integer in minor units (1000 for €10.00) not a decimal (10.00)?
6. Check rate limits - Are you under the limit?