Перейти к содержимому

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

Все ошибочные ответы возвращаются в едином формате:

{
"error": {
"code": "<machine-readable code>",
"message": "<человекочитаемое описание>"
}
}

HTTP status совпадает с типом ошибки. Конверт стабилен - code - это контракт, можно строить switch по нему.

HTTPcodeКогда
400validation_errorНевалидное тело (пустое имя, неверный scope, неверный formatы). message объясняет что именно.
401invalid_tokenТокен отсутствует, неверного формата, неверный hash, или удалён.
401token_expiredСрок ключа истёк - создайте новый.
401token_revokedКлюч отозван - Revoke в UI.
403insufficient_scopeУ ключа нет требуемого scope. Заголовок WWW-Authenticate указывает требуемый scope.
403plan_limitАккаунт в limited-mode (превышены лимиты плана).
403limit.projectsПревышен лимит проектов вашего тарифа.
404(без code)Ресурс не найден (или принадлежит другому аккаунту - намеренно не различаем чтобы не раскрывать существование).
412version_mismatchStale If-Match на PATCH /tasks/{id} - задача была обновлена кем-то ещё. Заголовок ETag ответа содержит актуальную версию.
429rate_limitedПревышен rate limit. Заголовок Retry-After - секунды до повторной попытки.
import requests
from time import sleep
def call(url, **kwargs):
while True:
r = requests.post(url, **kwargs)
if r.status_code == 200:
return r.json()
if r.status_code == 429:
sleep(int(r.headers.get('Retry-After', '30')))
continue
err = r.json().get('error', {})
code = err.get('code', '')
if code in ('token_expired', 'token_revoked'):
raise RuntimeError(f'Need new API key: {code}')
if code == 'insufficient_scope':
raise RuntimeError(f'Missing scope: {r.headers.get("WWW-Authenticate", "")}')
raise RuntimeError(f'{r.status_code} {code}: {err.get("message", "")}')