Ошибки Claude API
Справочник по ошибкам Claude API: форматы ответов, значения HTTP-кодов, возможные причины и правила безопасного повтора запросов.
Обновлено: 25 июля 2026 года.
Формат ошибки
Claude API Tech может возвращать ошибки в Anthropic- или OpenAI-совместимом формате. В обоих случаях объект error содержит тип ошибки и пояснение.
Anthropic Error Format
JSON
{
"type": "error",
"error": {
"type": "rate_limit_error",
"message": "Rate limit exceeded"
},
"request_id": "req_..."
}OpenAI Error Format
JSON
{
"error": {
"message": "Invalid model ID",
"type": "invalid_request_error",
"code": "invalid_model"
}
}Все типовые HTTP-ошибки
| HTTP | Тип | Что означает |
|---|---|---|
| 400 | invalid_request_error | Неверный JSON, обязательное поле отсутствует, параметр не поддерживается моделью или нарушена структура messages. |
| 401 | authentication_error | API-ключ отсутствует, имеет неверный формат, отозван или истёк. |
| 403 | permission_error | Ключ распознан, но у него нет доступа к модели, workspace или другому ресурсу. |
| 404 | not_found_error | Endpoint, модель или ресурс с указанным ID не найден. |
| 409 | conflict_error | Запрос конфликтует с текущим состоянием ресурса, например из-за одновременного изменения. |
| 413 | request_too_large | HTTP-тело превышает лимит размера. Для Messages API и Token Counting API лимит Anthropic — 32 МБ. |
| 429 | rate_limit_error | Превышен лимит запросов или входных/выходных токенов; возможен также acceleration limit при резком росте нагрузки. |
| 500 | api_error | Непредвиденная внутренняя ошибка API. |
| 504 | timeout_error | API не успел обработать запрос. |
| 529 | overloaded_error | API временно перегружен общим трафиком. |
Правила безопасного повтора
Повторяйте только временные ошибки и увеличивайте паузу между попытками.
- 1Повторяйте запросы при 429, 500, 504 и 529. Остальные 4xx сначала требуют исправления запроса.
- 2Всегда соблюдайте retry-after, если сервер вернул этот заголовок.
- 3Без retry-after используйте exponential backoff со случайным jitter и ограничением максимальной задержки.
- 4Ограничивайте число попыток, сохраняйте request_id и не повторяйте неидемпотентные операции вслепую.
const RETRYABLE = new Set([429, 500, 504, 529]); async function requestWithRetry(url: string, init: RequestInit) { for (let attempt = 0; attempt < 5; attempt++) { const response = await fetch(url, init); if (response.ok) return response; if (!RETRYABLE.has(response.status) || attempt === 4) { throw new Error(`Request failed: ${response.status}`); } const retryAfter = response.headers.get("retry-after"); const retryAfterSeconds = Number(retryAfter); const backoff = Math.min(500 * 2 ** attempt, 10_000); const delay = retryAfter !== null && Number.isFinite(retryAfterSeconds) ? retryAfterSeconds * 1000 : backoff + Math.random() * 250; await new Promise((resolve) => setTimeout(resolve, delay)); }}