Ошибки

Два формата

Ошибки приходят в одном из двух форматов — в зависимости от того, где запрос остановился.

Проверка подписи и лимитов — до разбора запроса. Код в поле error:

{
  "error": "unauthorized",
  "message": "unauthorized: X-Timestamp is outside the ±5 minute window — check the server clock"
}

Обработка запроса — RFC 9457, Content-Type: application/problem+json. Код в errors[0].value:

{
  "title": "Payment Required",
  "status": 402,
  "detail": "partner_balance_exhausted",
  "errors": [
    { "message": "balance_exhausted", "location": "error.code", "value": "balance_exhausted" }
  ]
}

Ветвитесь по коду, а не по тексту. message, detail и title — для людей и могут меняться. Код читается одной строкой:

const code = body?.error ?? body?.errors?.[0]?.value ?? `http_${status}`;

code = body.get("error") or (body.get("errors") or [{}])[0].get("value") or f"http_{status}"

$code = $body['error'] ?? ($body['errors'][0]['value'] ?? "http_$status");

Ошибки схемы

Если тело или параметры не соответствуют схеме (нет обязательного поля, неверный тип, нет заголовка Idempotency-Key), ответ — 422 без кода; что не так, написано в errors[].location и errors[].message:

{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "validation failed",
  "errors": [
    {
      "message": "expected required property email to be present",
      "location": "body",
      "value": { "external_id": "cust-42", "first_name": "Ivan", "last_name": "Petrov" }
    }
  ]
}

Коды подписи и лимитов

Формат с полем error.

Коды обработки

Формат RFC 9457, код в errors[0].value.

Код error в формате RFC 9457 означает ошибку без отдельного кода: ориентируйтесь на HTTP-статус и detail.

Коды неудачной операции

Если операция завершилась failed или needs_review, причина — в error_code операции и события.

Коды provider_unavailable, maintenance, tariff_not_available и issue_not_started относятся к картам. Покупка eSIM завершается неуспешно с provider_rejected, refunded, needs_review или unknown_order_status; подробности — в разделе eSIM.