Errors and retries

Check the HTTP status and response body together. Most errors include a detail field; it can be a string, a list of field errors, or a structured validation result.

{
  "detail": "Invalid Labs credential"
}

HTTP status codes

Status	Next action
`400`	Check the request values and required configuration
`401`	Check the Labs credential and its expiry
`402`	Review the workspace’s available usage or quota
`403`	Check workspace membership, permissions, and any required Labs role
`404`	Check the identifier, active status, and published version
`409`	Resolve the reported state or identifier conflict
`422`	Correct the fields or workflow errors in the response
`429`	Reduce request frequency and honor `Retry-After` if present
`500`, `502`, `503`, `504`	Check whether the operation completed before retrying

Workflow validation

The validation endpoint returns is_valid and errors. Publishing an invalid definition can return the same result inside detail.

{
  "detail": {
    "is_valid": false,
    "errors": [
      {
        "kind": "node",
        "id": "start-1",
        "field": "data.prompt",
        "message": "Prompt cannot be empty"
      }
    ]
  }
}

This illustrates the response shape; error messages depend on the failed check. Use kind, id, and field to locate the item to correct.

Retry carefully

Retry read-only requests with bounded exponential backoff after a transient error. Do not blindly retry a request that starts a call, starts a campaign, creates a resource, or invokes an action: it might have succeeded before the response was lost. Check recent runs or the resource state first. Record the status, time, target agent, and any returned run ID in your own application logs. Keep keys and customer content out of diagnostic logs.

Authentication & Errors

Resources

HTTP status codes

Workflow validation

Retry carefully

​HTTP status codes

​Workflow validation

​Retry carefully

HTTP status codes

Workflow validation

Retry carefully