Errors & rate limits

Error shape

Errors share this shape:

{ "error": { "type": "<error_code>", "message": "<detail>" } }

When troubleshooting, record the X-TT-Request-ID response header — with it you can locate a single call's billing and error detail on the console "Requests" page.

Common error codes

HTTP	type	Meaning	What to do
401	unauthorized	Missing or invalid API key	Check the Authorization header and that the key is correct / not disabled
402	billing_shortfall	Wallet balance insufficient	Go to Recharge
402	api_key_quota_exceeded	Over this key's monthly limit	Raise the limit, or use another key
403	model_not_allowed	Model not in the key's scope	Adjust key scope, or use an allowed model
403	ip_not_allowed	Source IP not permitted	Adjust the key's IP restriction / source
404	—	Path not found	Check whether the base URL's /v1 is one too many / few; check the model path
429	rate_limited	Rate limited	Retry after Retry-After
5xx	—	Temporary service error	Retry later; if it persists, contact support with the request id

Error details

When a call fails, the platform returns a structured error. message usually contains a readable reason; type is for programmatic checks. Retry retryable errors with backoff.

Rate limits

On a rate limit you get 429 with these response headers:

Header	Meaning
Retry-After	Suggested seconds to wait before retrying
X-RateLimit-Limit	Requests-per-minute limit
X-RateLimit-Remaining	Remaining calls in the current window
X-RateLimit-Reset	When the quota resets

Recommendation: implement exponential backoff on the client and respect Retry-After.

When you aren't charged

• Requests rejected before processing — auth failure (401), rate limit (429), bad params — are not charged.
• Tasks that fail / cancel / expire are not charged; the hold is released.
• Streaming requests, even if cut off mid-way, settle on real usage as best they can — see Recharge & Billing.

Still stuck?

Bring this info to support for a fast diagnosis:

1. X-TT-Request-ID (response header).
2. Approximate time, the model used, the API path.
3. The full error response body (error.type + message).