Error Handling

All Thinklio API surfaces return errors in a consistent JSON format.

Error Response Shape

``json { "error": { "code": "rate_limit_exceeded", "message": "You have exceeded the rate limit for this endpoint. Retry after 30 seconds.", "details": { "limit": 60, "remaining": 0, "reset_at": "2026-03-19T12:01:00Z" }, "request_id": "req_01hxyz..." } } ``

Always include the request_id when contacting support.

HTTP Status Codes

| Status | Meaning | |--------|---------| | 200 | Success | | 201 | Created | | 400 | Bad request — malformed payload or missing required field | | 401 | Unauthenticated — missing or invalid API key | | 403 | Forbidden — authenticated but not authorised for this action | | 404 | Not found — resource does not exist or is not visible to your key | | 409 | Conflict — duplicate resource or state conflict | | 422 | Unprocessable — payload is valid JSON but fails validation | | 429 | Rate limited — slow down and retry after the Retry-After header | | 500 | Internal error — Thinklio fault, not yours |

Common Error Codes

| Code | Description | |------|-------------| | invalid_api_key | API key is missing, malformed, or revoked | | insufficient_scope | API key does not have permission for this operation | | budget_exceeded | Org or team budget is exhausted | | policy_violation | Action blocked by an org or team policy | | agent_not_found | Agent ID does not exist or is not accessible | | session_expired | Conversation session has expired | | rate_limit_exceeded | Too many requests; see Retry-After header | | tool_unavailable | Registered external tool is unreachable |

Retries

For 429 and 5xx responses, retry with exponential backoff. Honour the Retry-After header when present. For 4xx responses (except 429), retrying without fixing the request will not help.