Error reference

Error responses

Most API errors use a detail property:

{"detail": "Permission denied: requires 'runs.trigger'"}

detail is not always a string. Request validation commonly returns a list:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "flow_name"],
      "msg": "Field required",
      "input": {}
    }
  ]
}

Validation entries may contain additional fields. Dependency build validation can return detail.validation_errors. AI Studio can return an operation-specific validation envelope with workflow_errors and updated session state. Retain a sanitized copy of an unexpected body instead of assuming every failure has a string message.

Status guide

Some unavailable integration features intentionally return 404. Do not infer that credentials are invalid merely because one feature is unavailable.

Retry policy

For a transient read failure, use exponential backoff with random jitter and a maximum attempt count. Honor Retry-After when present; clients also need a fallback delay because this header is not guaranteed for every error response. A reasonable application policy starts at one second, doubles the maximum delay on each attempt, and caps it at 30 seconds.

Do not retry validation or permission failures without changing the request or credentials. Monthly quota exhaustion requires a quota reset or an account change; short sleeps will not resolve it.

Before retrying a write after a network timeout, determine whether it took effect:

• Repeating POST /runs can create duplicate runs. Inspect recent runs and make business operations idempotent.
• A dependency build may have started even if its response was lost. Read packaging_status first.
• Multipart uploads should resume with their original identifiers while URLs remain valid. Abort an abandoned upload before starting again.
• Cancellation is repeatable for a run already in CANCELLATION_REQUESTED or CANCELLED.

Diagnose a failed run

1. Read GET /runs/{run_id} and inspect status, error_message, and task_runs.
2. Read GET /runs/{run_id}/logs and follow all returned cursors.
3. Check parameters, deployment version, environment, enabled variables, secrets, connectors, and dependency packages.
4. Correct the cause before using retry or backfill.

Cancellation does not undo external writes. A timeout or failed task can occur after a destination accepted data. Use stable business identifiers or destination-supported deduplication to make recovery safe.

Information to retain for support

Keep the UTC timestamp, HTTP method and relative path, response status, your X-Request-Id, workspace ID, and run/deployment identifier. Include a minimal redacted request and error body. Remove bearer tokens, signed URLs, secret values, customer data, and webhook tokens before sharing logs.