# Errors

Errors are returned as JSON with a consistent shape:

```json
{
  "error": {
    "code": "insufficient_credits",
    "message": "Workspace balance is below the minimum required to start a run.",
    "details": {
      "balanceCents": 120,
      "requiredCents": 500
    }
  }
}
```

## Status codes

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `400` | Bad request — invalid body or query parameters. |
| `401` | Missing or invalid API key. |
| `403` | Authenticated but not allowed to perform this action. |
| `404` | Resource not found, or not visible to this workspace. |
| `409` | Conflict — e.g. cancelling a run that's already finished. |
| `422` | Validation error — body shape is correct but values are invalid. |
| `429` | Rate limited — back off and retry. |
| `500` | Server error — safe to retry with backoff. |

## Common error codes

- `unauthorized` — API key missing or invalid.
- `forbidden` — key lacks the required scope.
- `not_found` — resource does not exist or is in another workspace.
- `validation_error` — request body failed validation.
- `insufficient_credits` — workspace balance below the minimum required to start a run.
- `rate_limited` — too many requests; see `Retry-After`.
- `plan_blocked` — plan is in `blocked` readiness and cannot be run.