Обработка ошибок

API использует стандартные HTTP-коды. Успешные ответы возвращают тело ресурса напрямую. Ошибки соответствуют RFC 9457 Problem Details for HTTP APIs (application/problem+json) и добавляют поля сверх стандарта (extension members, RFC 9457 §3.2): верхнеуровневое code для обработки в коде и верхнеуровневое field (snake_case) при ошибке валидации по одному полю. Когда не проходят сразу несколько полей, field заменяется массивом errors[] с детализацией по каждому из них.

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

Любая ошибка соответствует RFC 9457 Problem Details for HTTP APIs, отдаётся как Content-Type: application/problem+json.

Одиночная ошибка (большинство ответов)

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

Несколько ошибок валидации

Возвращается, только когда валидацию не проходят сразу несколько полей. Код верхнего уровня (code) всегда validation_failed; детализация по полям — в 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." }
  ]
}

Описание полей

Зачем структурированные коды (а не только message)

Текст в message и detail может изменяться между версиями, локализоваться или дополняться контекстом. Стабильный контракт — это code. После публикации код никогда не меняет семантику. Используйте code для логики обработки и локализации.

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),
}

Типы ошибок

Каждый статус приходит в конверте ошибки с полем title и машиночитаемым code. Один статус может покрывать несколько сценариев — ветвитесь по code, а не по статусу.

Для логики клиента используйте именно code, а не HTTP-статус — несколько разных бизнес-сценариев делят один HTTP-код, и машинный code в ответе их различает.

Лимиты запросов

API по умолчанию допускает 30 запросов в секунду на мерчанта, а на POST /v1/invoices действует более строгий лимит — 5 запросов в секунду. Лимит считается на мерчанта, в окне в одну секунду: все ваши ключи расходуют общий бюджет. Оба лимита настраиваются индивидуально для мерчанта. При превышении вернётся 429 Too Many Requests с заголовком Retry-After: 1.

{
  "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"
}