/docs/api/errors
Errors & limits
Every obsrv API response uses standard HTTP status codes. Errors return a JSON body with a stable code, a human message, and (when applicable) a list of field errors.
Error shape
{
"error": {
"code": "invalid_request",
"message": "steps[0].messages[0].role is required",
"fields": [
{ "path": "steps[0].messages[0].role", "issue": "missing" }
]
}
}Status codes
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | Body failed schema validation. The error body lists the offending fields. |
| 401 | unauthorized | API key is missing, malformed, or revoked. |
| 403 | forbidden | Authenticated, but the resource isn't owned by your org/project. |
| 404 | not_found | Resource doesn't exist (or your key can't see it). |
| 409 | conflict | Idempotency or unique-constraint violation. |
| 413 | payload_too_large | Trace or media payload exceeds the per-call size limit. |
| 422 | unprocessable_entity | Schema is structurally valid but semantically rejected. |
| 429 | rate_limited | You exceeded the per-project rate limit. Honor the Retry-After header. |
| 500 | internal_error | An unexpected server error. Safe to retry with backoff. |
| 503 | service_unavailable | Maintenance or partial outage. Retry. |
Per-request limits
- Trace payload: 8 MB hard cap. Use the steps endpoint or media upload for larger evidence.
- Single media upload: 100 MB.
- Steps NDJSON batch: 5,000 lines per request.
- Search query: 25 results default, 250 max.