Errors & Rate Limits

Error response format, all error codes, and rate limit details.

Error format

All errors follow the same JSON shape:

{
  "error": {
    "message": "Human-readable description",
    "type": "error_category",
    "code": "machine_readable_code",
    "param": null
  }
}

Error codes

Status	code	Meaning
400	invalid_json	Request body is not valid JSON
400	missing_messages	The `messages` field is missing or empty
401	missing_api_key	No API key in Authorization header
401	invalid_api_key	API key not found or revoked
402	insufficient_balance	Account balance below $0.01
402	key_spend_limit_reached	Key's all-time spend reached its cap
403	filter_not_allowed	Filter not available on your plan
403	task_type_not_allowed	Task type blocked by key config
403	model_not_allowed	Routed model not in key's allowlist
403	model_denied	Routed model is in key's blocklist
422	no_model_available	No model satisfies filters + task type
429	rate_limit_exceeded	Burst rate limit hit
502	provider_error	Upstream provider failed after retries

Rate limits

Rate limits are per-user (not per-key) using a sliding window.

Plan	Requests / second
Starter	10
Builder	60
Scale	300

When rate-limited, the response includes a Retry-After header (in seconds). Wait that long before retrying.