Errors

Errors are returned as JSON with a consistent shape:

{
  "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.