Errors & conventions
Response envelope
Every response is JSON with a status field.
200 Success
{ "status": "success", "...": "endpoint-specific fields" }402 Error
{ "status": "error", "code": "QUOTA_EXCEEDED", "message": "Out of credits" }The code is a stable, machine‑readable string — branch on it rather than on the
human‑readable message.
Error codes
| HTTP | code | Meaning |
|---|---|---|
| 400 | (varies) | Bad input |
| 401 | AUTH_MISSING | No Bearer token |
| 401 | AUTH_INVALID | Bad, expired or revoked credential |
| 402 | QUOTA_EXCEEDED | Out of credits — top up or upgrade |
| 403 | SCOPE_FORBIDDEN | Key lacks the scope for that service |
| 404 | UNKNOWN_SERVICE | No such service |
| 413 | PAYLOAD_TOO_LARGE | Upload over the size limit (15 MB default) |
| 415 | UNSUPPORTED_MEDIA_TYPE | File type not allowed |
| 429 | RATE_LIMITED | Too many requests this minute |
Rate limiting
Rate‑limited responses (429) include headers so you can back off gracefully:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed per minute |
X-RateLimit-Remaining | Requests left in the current window |
When you hit 429, wait until the next minute before retrying. For batch workloads,
spread requests evenly rather than bursting.