Error Response Format
All Tiro API errors follow a consistent JSON structure:{
"error": {
"code": 400001,
"errorType": "bad_request",
"message": "Human readable error message",
"detail": "Additional context or null"
}
}
Fields
| Field | Type | Description |
|---|---|---|
code | integer | 6-digit error code in AAABBB form: first 3 digits match the HTTP status, last 3 digits are a per-status serial. Use this for fine-grained client branching. |
errorType | string | Coarse-grained category derived from the HTTP status. Stable over time — safe for client branching. See table below. |
message | string | Human-readable error message. Not stable; do not use for branching. |
detail | object | string | null | Optional additional context (varies per error). |
HTTP Status Codes & Error Types
| Status | errorType | Meaning |
|---|---|---|
| 400 | bad_request | Invalid request format or parameters |
| 401 | unauthorized | Missing or invalid API key |
| 403 | forbidden | API key lacks required permissions |
| 404 | not_found | Resource doesn’t exist |
| 406 | not_acceptable | Unsupported Accept header |
| 409 | conflict | Resource already exists or state conflict |
| 413 | payload_too_large | Request body exceeds size limits |
| 422 | unprocessable_entity | Valid format but invalid data |
| 429 | too_many_requests | Rate limit exceeded |
| 5xx | internal_error | Server-side error (do not parse further; retry with backoff) |