Errors
Every error code, what it means and what to do.
json
{
"error": { "code": "insufficient_scope", "message": "This key doesn't have the agents:run scope. Create a key with it under API keys." },
"request_id": "req_..."
}| Status | code | What to do |
|---|---|---|
| 400 | invalid_request / invalid_json | Fix the body; the message names the field. |
| 401 | unauthorized | Send a valid, unrevoked key as Authorization: Bearer gsk_… |
| 402 | insufficient_credit | Add credit under Billing. Nothing was run or charged. |
| 402 | spend_limit_reached | Raise the monthly limit under Billing, or wait for next month. |
| 403 | insufficient_scope | Use a key with the endpoint's scope. |
| 403 | environment_mismatch | Use a key from the agent's environment. |
| 404 | agent_not_found / run_not_found / action_not_found | Check the id and that it's in this workspace. |
| 409 | agent_not_active | Resume the agent. |
| 409 | action_not_authorized | Only authorized actions can report a result. |
| 429 | rate_limited | More than 600 requests a minute for this key. Retry after retry-after seconds. |
| 503 | model_not_configured | The deployment has no model provider configured. |
| 500 | internal_error | Retry. Quote the request id if it persists. |
Run failures come back as a run with status failed and error.code (for example model_error or max_steps_reached), not as an HTTP error, so you still get the steps and usage.
Something wrong or missing? Tell us · Stuck? Help center