Обработка ошибок
Все ошибочные ответы возвращаются в едином формате:
{ "error": { "code": "<machine-readable code>", "message": "<человекочитаемое описание>" }}HTTP status совпадает с типом ошибки. Конверт стабилен - code - это контракт, можно строить switch по нему.
Каталог кодов
Заголовок раздела «Каталог кодов»| HTTP | code | Когда |
|---|---|---|
| 400 | validation_error | Невалидное тело (пустое имя, неверный scope, неверный formatы). message объясняет что именно. |
| 401 | invalid_token | Токен отсутствует, неверного формата, неверный hash, или удалён. |
| 401 | token_expired | Срок ключа истёк - создайте новый. |
| 401 | token_revoked | Ключ отозван - Revoke в UI. |
| 403 | insufficient_scope | У ключа нет требуемого scope. Заголовок WWW-Authenticate указывает требуемый scope. |
| 403 | plan_limit | Аккаунт в limited-mode (превышены лимиты плана). |
| 403 | limit.projects | Превышен лимит проектов вашего тарифа. |
| 404 | (без code) | Ресурс не найден (или принадлежит другому аккаунту - намеренно не различаем чтобы не раскрывать существование). |
| 412 | version_mismatch | Stale If-Match на PATCH /tasks/{id} - задача была обновлена кем-то ещё. Заголовок ETag ответа содержит актуальную версию. |
| 429 | rate_limited | Превышен rate limit. Заголовок Retry-After - секунды до повторной попытки. |
Пример обработки
Заголовок раздела «Пример обработки»import requestsfrom 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", "")}')