API Errors and How to Fix Them

Overview

Errors use the OpenAI format, with the request id alongside. The code tells you what went wrong, and the message says what to do.

{
  "error": {
    "message": "This request would exceed the rate limit for your organization of 150 requests per minute on Pulse and Orbit. Retry after 2s, …",
    "type": "rate_limit_error",
    "param": null,
    "code": "rate_limit_exceeded"
  },
  "request_id": "req_0b6f…"
}

Errors by status

Status	code	What it means and what to do
400	context_length_exceeded	The messages don't fit in the 131,072-token context window. Shorten them.
400	content_policy_violation	Content moderation declined the request. It isn't charged. Change the request; retrying it unchanged won't help.
400	invalid_image, image_too_large	Not a JPEG, PNG, WebP or GIF Torki can read, damaged, over 20 MB or over 25 megapixels.
400	invalid_video, video_too_large	Not a supported video, unreadable, longer than 10 minutes or over 100 MB.
400	invalid_media_url, media_fetch_failed	The image or video link isn't a public http(s) address on port 80 or 443, or downloading it failed or took over 30 seconds.
400	too_many_images	More than 8 images in the request, video frames included.
400	usage_limit_reached	A monthly spend limit you set, for the organization or a workspace. Raise it, or wait for the 1st (UTC).
400	(varies)	Another invalid field; param names it.
401	invalid_api_key	The key is missing, unknown, revoked, disabled or expired. Send it as Authorization: Bearer tk_live_..., or create a new key.
402	insufficient_balance	Not enough credit. Add funds in Settings → Billing.
403	beta_access_required	API access for this organization, or for the account that created the key, was turned off. Contact support@torkiai.com.
404	model_not_found	Unknown model id. Use torki-pulse, torki-orbit, torki-stellar or torki-cosmos.
429	rate_limit_exceeded	Too many requests or tokens. Retry after retry-after.
429	concurrency_limit_exceeded	Your organization already has its tier's number of requests in flight. Retry after retry-after, or when one finishes.
429	spend_cap_reached	Your tier's monthly spend cap. No retry-after: it resets on the 1st, or buy credit to move up a tier.
503	overloaded	Torki's model servers, or its image and video processing, are busy. Retry with backoff.
504	upstream_timeout	The model took too long. Retry.

Which errors to retry

• Retry with backoff: 429 rate_limit_exceeded and concurrency_limit_exceeded (wait at least retry-after seconds), 503 overloaded and 504 upstream_timeout. OpenAI SDKs retry 429 responses automatically.
• Don't retry in a loop: 402 (add credit first), 429 spend_cap_reached and 400 usage_limit_reached (a limit has to change first), 401, 403 and 404.
• Fix the request: any other 400. param names the field at fault.

Errors during a stream

An error after a stream has started arrives as a final data: {"error": {...}} event followed by data: [DONE]. The tokens produced before the error are charged.

Reporting a problem

Every response includes a request-id header (also x-request-id), and errors carry request_id in the body. Find the request in Logs in Torki Platform: Request details shows its status, error code, model, tokens and cost, and has Copy request id. When you contact support@torkiai.com, include the request id, the time (UTC) and the model.

FAQ

I get 401 with a key that starts with tk_.

Torki agent keys, from a published agent, also start with tk_ but don't work with the Torki API. Create a key on API keys in Torki Platform; it starts with tk_live_.

I get 402 although my balance isn't zero.

A request starts only if your credit covers its estimated cost, and a thinking request on Stellar or Cosmos needs enough for its whole thinking budget. See Thinking Models: Stellar and Cosmos.

Where is the full error message after the fact?

It went back to your code in the response body. Logs keep only the error code.