Cosmos uses standard HTTP status codes and returns structured error information to help you diagnose and resolve issues programmatically.HTTP Status Codes#
| Code | Meaning | Action |
|---|
| 200 | All flight legs processed successfully | No action needed |
| 207 | Partial success — some legs succeeded, some failed | Check results array for per-leg status |
| 401 | Authentication failed | Verify your API key |
| 422 | Batch size exceeds limit (max 50) | Reduce number of flight legs |
| 429 | Rate limit exceeded (60 req/min) | Wait for Retry-After header, then retry |
Partial success (207)#
This is the most important status to handle correctly.
results array where each entry has a status of either "success" or "failed".For failed entries, the errors array contains ValidationError objects with a dot-notation field path (e.g., delays[0].code) and a human-readable message.Common validation errors#
Error response structure#
All error responses (401, 422, 429) return the same structure:{
"errors": [
{
"code": "not_authorized | request_size_exceeded | rate_limit_exceeded",
"detail": null,
"source": null
}
]
}
Retry strategy#
| Status | Action |
|---|
| 401 | Do not retry — fix credentials. Error code: not_authorized |
| 422 | Do not retry — reduce batch size. Error code: request_size_exceeded |
| 429 | Wait for Retry-After header value, then retry. Error code: rate_limit_exceeded |
| 207 | Retry only the failed legs after fixing validation issues |
| 5xx | Retry with exponential backoff (start at 1s, max 60s) |
Troubleshooting#
