mirror of
https://github.com/Piebald-AI/claude-code-system-prompts.git
synced 2026-05-30 21:54:18 +08:00
175 lines
5.4 KiB
Markdown
175 lines
5.4 KiB
Markdown
<!--
|
|
name: 'Data: HTTP error codes reference'
|
|
description: Reference for HTTP error codes returned by the Claude API with common causes and handling strategies
|
|
ccVersion: 2.1.47
|
|
-->
|
|
# HTTP Error Codes Reference
|
|
|
|
This file documents HTTP error codes returned by the Claude API, their common causes, and how to handle them. For language-specific error handling examples, see the \`python/\` or \`typescript/\` folders.
|
|
|
|
## Error Code Summary
|
|
|
|
| Code | Name | Retryable | Common Cause |
|
|
| ---- | --------------------- | --------- | ------------------------------------ |
|
|
| 400 | Bad Request | No | Invalid request format or parameters |
|
|
| 401 | Unauthorized | No | Invalid or missing API key |
|
|
| 403 | Forbidden | No | API key lacks permission |
|
|
| 404 | Not Found | No | Invalid endpoint or model ID |
|
|
| 413 | Request Too Large | No | Request exceeds size limits |
|
|
| 422 | Unprocessable Entity | No | Semantic validation error |
|
|
| 429 | Rate Limited | Yes | Too many requests |
|
|
| 500 | Internal Server Error | Yes | Anthropic service issue |
|
|
| 529 | Overloaded | Yes | API is temporarily overloaded |
|
|
|
|
## Detailed Error Information
|
|
|
|
### 400 Bad Request
|
|
|
|
**Causes:**
|
|
|
|
- Malformed JSON in request body
|
|
- Missing required parameters (\`model\`, \`max_tokens\`, \`messages\`)
|
|
- Invalid parameter types (e.g., string where integer expected)
|
|
- Empty messages array
|
|
- Messages not alternating user/assistant
|
|
|
|
**Example error:**
|
|
|
|
\`\`\`json
|
|
{
|
|
"type": "error",
|
|
"error": {
|
|
"type": "invalid_request_error",
|
|
"message": "messages: roles must alternate between \\"user\\" and \\"assistant\\""
|
|
}
|
|
}
|
|
\`\`\`
|
|
|
|
**Fix:** Validate request structure before sending. Check that:
|
|
|
|
- \`model\` is a valid model ID
|
|
- \`max_tokens\` is a positive integer
|
|
- \`messages\` array is non-empty and alternates correctly
|
|
|
|
---
|
|
|
|
### 401 Unauthorized
|
|
|
|
**Causes:**
|
|
|
|
- Missing \`x-api-key\` header or \`Authorization\` header
|
|
- Invalid API key format
|
|
- Revoked or deleted API key
|
|
|
|
**Fix:** Ensure \`ANTHROPIC_API_KEY\` environment variable is set correctly.
|
|
|
|
---
|
|
|
|
### 403 Forbidden
|
|
|
|
**Causes:**
|
|
|
|
- API key doesn't have access to the requested model
|
|
- Organization-level restrictions
|
|
- Attempting to access beta features without beta access
|
|
|
|
**Fix:** Check your API key permissions in the Console. You may need a different API key or to request access to specific features.
|
|
|
|
---
|
|
|
|
### 404 Not Found
|
|
|
|
**Causes:**
|
|
|
|
- Typo in model ID (e.g., \`claude-sonnet-4.6\` instead of \`claude-sonnet-4-6\`)
|
|
- Using deprecated model ID
|
|
- Invalid API endpoint
|
|
|
|
**Fix:** Use exact model IDs from the models documentation. You can use aliases (e.g., \`claude-opus-4-6\`).
|
|
|
|
---
|
|
|
|
### 413 Request Too Large
|
|
|
|
**Causes:**
|
|
|
|
- Request body exceeds maximum size
|
|
- Too many tokens in input
|
|
- Image data too large
|
|
|
|
**Fix:** Reduce input size — truncate conversation history, compress/resize images, or split large documents into chunks.
|
|
|
|
---
|
|
|
|
### 422 Unprocessable Entity
|
|
|
|
**Causes:**
|
|
|
|
- \`max_tokens\` exceeds model's limit
|
|
- Invalid \`temperature\` value (must be 0.0-1.0)
|
|
- \`budget_tokens\` >= \`max_tokens\` in extended thinking
|
|
- Invalid tool definition schema
|
|
|
|
**Common mistake with extended thinking:**
|
|
|
|
\`\`\`
|
|
# Wrong: budget_tokens must be < max_tokens
|
|
thinking: budget_tokens=10000, max_tokens=1000 → Error!
|
|
|
|
# Correct
|
|
thinking: budget_tokens=10000, max_tokens=16000
|
|
\`\`\`
|
|
|
|
---
|
|
|
|
### 429 Rate Limited
|
|
|
|
**Causes:**
|
|
|
|
- Exceeded requests per minute (RPM)
|
|
- Exceeded tokens per minute (TPM)
|
|
- Exceeded tokens per day (TPD)
|
|
|
|
**Headers to check:**
|
|
|
|
- \`retry-after\`: Seconds to wait before retrying
|
|
- \`x-ratelimit-limit-*\`: Your limits
|
|
- \`x-ratelimit-remaining-*\`: Remaining quota
|
|
|
|
**Fix:** The Anthropic SDKs automatically retry 429 and 5xx errors with exponential backoff (default: \`max_retries=2\`). For custom retry behavior, see the language-specific error handling examples.
|
|
|
|
---
|
|
|
|
### 500 Internal Server Error
|
|
|
|
**Causes:**
|
|
|
|
- Temporary Anthropic service issue
|
|
- Bug in API processing
|
|
|
|
**Fix:** Retry with exponential backoff. If persistent, check [status.anthropic.com](https://status.anthropic.com).
|
|
|
|
---
|
|
|
|
### 529 Overloaded
|
|
|
|
**Causes:**
|
|
|
|
- High API demand
|
|
- Service capacity reached
|
|
|
|
**Fix:** Retry with exponential backoff. Consider using a different model (Haiku is often less loaded), spreading requests over time, or implementing request queuing.
|
|
|
|
---
|
|
|
|
## Common Mistakes and Fixes
|
|
|
|
| Mistake | Error | Fix |
|
|
| ------------------------------- | ---------------- | ------------------------------------------------------- |
|
|
| \`budget_tokens\` >= \`max_tokens\` | 422 | Ensure \`budget_tokens\` < \`max_tokens\` |
|
|
| Typo in model ID | 404 | Use valid model ID like \`claude-opus-4-6\` |
|
|
| First message is \`assistant\` | 400 | First message must be \`user\` |
|
|
| Consecutive same-role messages | 400 | Alternate \`user\` and \`assistant\` |
|
|
| API key in code | 401 (leaked key) | Use environment variable |
|
|
| Custom retry needs | 429/5xx | SDK retries automatically; customize with \`max_retries\` |
|