Що каже код помилки API

Коли API відхиляє запит або не може його виконати, у його відповіді є код — стале ім’я того, що сталося. Ця сторінка перелічує коди, якими відповідає API, і каже, що означає кожен і що з ним робити. Розгалужуйтеся за кодом, а не за повідомленням.

Конверт помилки

Помилка, про яку API повідомляє сам, приходить в одному конверті. Стаття Огляд описує його поля й ті нечисленні відповіді, які приходять без нього.

{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget 74438200973595137 (monthly) exceeded",
    "request_id": "7c2e9a41-3b8d-4f6a-9e15-c04d2b7a8f63"
  }
}

Код, який несе більше, кладе це в details. Пул, у якого закінчилися підключення, називає там останній збій виклику.

{
  "error": {
    "code": "pool_exhausted",
    "message": "No provider connection could serve the request after 3 attempt(s)",
    "details": { "last_error_code": "provider_rate_limit" },
    "request_id": "0d3c1b9e-5a47-4f0e-9a36-2f6c8d1e7b42"
  }
}

Поруч із кожним кодом таблиці нижче друкують HTTP-статус, яким API на нього відповідає, — два для коду з двома значеннями, — і прочерк для коду, яким ніколи не відповідають на запит.

SDK зберігають код

Обидва SDK викидають помилку на відповідь-помилку, і помилка зберігає код API: code у Node.js, errorCode у PHP. Перша таблиця нижче називає тип, який кожен SDK викидає для її кодів. У кодів двох інших таблиць власного типу немає, і правило під кожною з цих таблиць каже, який тип викидає SDK. Стаття Обробка помилок показує, як їх ловити.

Коди, для яких у SDK є тип

Для цих кодів кожен SDK викидає власний тип. Більшість із них приходить від операцій, які викликає SDK: запиту до флоу та його викликів моделі, кредитів клієнта.

Коди без власного типу

Для цих кодів у SDK немає власного типу. Він викидає тип за статусом відповіді — за правилом під таблицею.

Коди консолі й налаштувань

Ці коди приходять від операцій консолі й налаштувань: входу й сесій, організацій і проєктів, учасників і запрошень, ключів, політик, бюджетів, флоу та їхніх версій, погоджень, сповіщень, вебхуків, підключень і пулів, оновлень консолі в реальному часі, — а invalid_date_range від списків реєстру, холдів і операцій. Жоден метод SDK ці операції не викликає. Правило під таблицею — правило SDK для будь-якого коду без власного типу.

Код, із яким закінчується виконання

Виконання, яке не завершилося, зберігає код в error_code, а error_message каже те саме реченням. Читання статусу, очікування й повтор запиту з його ключем читають обидва поля. Більшість цих кодів — коди цієї сторінки: код помилки, якою відповіли на запит. Два види — ні.

Вузол Відхилити запит завершує виконання з кодом і повідомленням, заданими в ньому. Вузол, у якому не задано ні того, ні іншого, завершує його так:

{
  "status": "rejected",
  "error_code": "rejected_by_flow",
  "error_message": "The request was rejected by the flow"
}

Середовище виконання закриває виконання, яке більше не може провести, із власним кодом: його обробник зупинився, воно чекало довше, ніж виконанню можна чекати, його стан не вдалося зберегти або прочитати. Що сталося, каже error_message. Виконання, яке чекало надто довго, закінчується так:

{
  "status": "failed",
  "error_code": "parked_expired",
  "error_message": "The execution waited longer than a parked execution may and was closed"
}

У виконання, яке закрила помилка без коду в API, немає ні того, ні іншого: error_code і error_message дорівнюють null.

Що читати далі

• Огляд — поля конверта й відповіді, які приходять без нього.

• Автентифікація — відмови ключу та його дозволам.

• Обробка помилок — ловіть помилки в SDK і дізнавайтеся, чи коштував виклик грошей.

• Асинхронні запуски й очікування — як прочитати, чим закінчилося виконання.

• Виконання — статус і код, з якими закінчилося виконання, через HTTP.

• Коли результат невідомий — що робити після operation_uncertain.