2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with Timbal servers (these are rare).
Rate limiting
Some endpoints enforce per-user rate limits. When limits apply, successful2xx responses and 429 Too Many Requests may include:
| Header | Meaning |
|---|---|
RateLimit-Limit | Maximum requests allowed in the current window. |
RateLimit-Remaining | Requests left before the window resets. |
RateLimit-Reset | Seconds until the window resets. |
Retry-After | On 429, seconds to wait before retrying (prefer this over a fixed backoff when present). |
X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset mirror the RateLimit-* values.
| Code | Status | Description |
|---|---|---|
| 200 | OK | Everything worked as expected. |
| 400 422 | Bad Requests | The request was unacceptable, often due to missing a required parameter. |
| 401 | Unauthorized | No valid API key provided. |
| 402 | Request Failed | The parameters were valid but the request failed. |
| 403 | Forbidden | The API key doesn’t have permissions to perform the request. |
| 404 | Not Found | The requested resource doesn’t exist. |
| 429 | Too Many Requests | Per-user rate limit exceeded. Honor Retry-After when sent; otherwise use exponential backoff. |
| 500 502 503 504 | Server Errors | Something went wrong on our end. |