Reference

Errors and limits

Every error is JSON with a message written to be shown to a person.

Error format

The Model API returns errors in the format of the wire you called, so SDKs raise their usual exceptions.

{
  "error": {
    "message": "Not enough credits for this request. Add credits under Billing, or lower max_tokens.",
    "type": "insufficient_credits",
    "code": "insufficient_credits"
  }
}

Status codes

StatusType (Model API)What to do
400invalid_request_errorThe request is malformed or not allowed. The message names the field. Fix it; don't retry as is.
401invalid_api_keyMissing, unknown or revoked key.
402insufficient_creditsYour balance can't cover the request or the swarm's budget. Add credits or lower max_tokens / budget_usd. Nothing was charged.
404model_not_foundUnknown model, or a swarm or file that doesn't exist. The message lists the models available.
429rate_limit_exceededToo many requests, or the model is busy. Wait a moment and retry with backoff. Nothing was charged.
502upstream_errorThe model provider failed after failover. Retry. Nothing was charged.
503service_unavailableThe model is not available right now.

Swarm API errors carry the message only, so branch on the HTTP status. One exception to the table: asking for a swarm while 3 are already working answers 400. Wait for one to finish, then send it again.

Limits

LimitValue
Model API requests300 per minute per key
Request body (Model API)8 MB, up to 2,000 messages
API keys per workspace50
Swarms working at once3 per workspace (paused and awaiting-approval swarms don't count)
Swarm budgets per key$500 committed per 24 hours
Swarm budget$1 to $100,000
Swarm task8,000 characters
Swarm deadline5 minutes to 48 hours
allow_domains20 verified domains
Paused swarm kept7 days

Need more? Tell us what you are building and we will raise them.