Error Handling

The API uses standard HTTP status codes. Successful responses return the resource body directly. Errors follow RFC 9457 Problem Details for HTTP APIs (application/problem+json) with two extension members: a top-level code you switch on programmatically, and a top-level field (snake_case) on single-field validation errors. When several fields fail at once, field is replaced by an errors[] array (a Paymos extension member, §3.2) carrying the per-field breakdown.

{
  "type": "https://paymos.io/docs/errors/codes#insufficient_balance",
  "title": "Conflict",
  "status": 409,
  "detail": "Merchant balance is insufficient.",
  "code": "insufficient_balance"
}

Every error response follows RFC 9457 Problem Details for HTTP APIs, served as Content-Type: application/problem+json.

Single error (most responses)

{
  "type": "https://paymos.io/docs/errors/codes#insufficient_balance",
  "title": "Conflict",
  "status": 409,
  "detail": "Merchant balance is insufficient.",
  "code": "insufficient_balance"
}

Multi-field validation

Only emitted when several fields fail validation at once. The top-level code is always validation_failed; per-field detail lives in errors[]:

{
  "type": "https://paymos.io/docs/errors/codes#validation_failed",
  "title": "Bad Request",
  "status": 400,
  "detail": "Validation failed.",
  "code": "validation_failed",
  "errors": [
    { "code": "field_required", "field": "currency", "message": "Currency is required." },
    { "code": "field_must_be_positive", "field": "amount", "message": "Amount must be > 0." }
  ]
}

Field reference

Why structured codes (and not just message)

message and detail text may evolve between versions, get localized, or be expanded with context. code is the stable contract — once a code is published, its semantics never change. Switch on code for programmatic handling and localization.

import { RateLimitError, ValidationError } from '@paymos/sdk';

try {
  await paymos.withdrawals.create(request);
} catch (error) {
  if (error instanceof ValidationError) {
    for (const item of error.errors) highlight(item.field, item.message);
  } else if (error instanceof RateLimitError) {
    scheduleRetry(error.retryAfterSeconds);
  }
  throw error;
}

use paymos::{ApiErrorKind, Error};

match paymos.withdrawals().create(&request).await {
    Ok(withdrawal) => process(withdrawal),
    Err(Error::Api(error)) if error.kind == ApiErrorKind::Validation => {
        for item in &error.errors {
            highlight(item.field.as_deref(), &item.message);
        }
    }
    Err(Error::Api(error)) if error.kind == ApiErrorKind::RateLimit => {
        schedule_retry(error.retry_after);
    }
    Err(error) => return Err(error),
}

Error types

Each status ships in the error envelope with a title and a machine-readable code. One status can cover several scenarios — branch on the code, not the status.

Always use code (not the HTTP status) to drive client logic — multiple distinct business scenarios share one HTTP status, and the wire code distinguishes them.

Rate limits

The API allows 30 requests per second per merchant by default, with a stricter limit on POST /v1/invoices (5 req/sec). Limits are counted per merchant, per one-second window — every API key you hold draws on the same budget — and both are configurable per merchant. When the limit is exceeded, you'll receive a 429 Too Many Requests response with a Retry-After: 1 header.

{
  "type": "https://paymos.io/docs/errors/codes#rate_limited",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded (30 req/sec). Retry after 1 second.",
  "code": "rate_limited"
}