Skip to main content

Errors, limits and retries

Check both the HTTP response and the operation's result. Receiving a response—or even receiving HTTP 200—does not always mean the requested work succeeded.

Read the response before deciding what to do​

Error formats vary between endpoints. A response may contain JSON with error, message, or err, or plain text such as Unauthorized. Check the status and content type before parsing; do not assume every response has the same JSON envelope.

HTTP statusWhat to checkWhat to do
400 Bad RequestRequired fields, types, identifiers, and request format.Correct the request before retrying.
401 UnauthorizedComplete credential, header format, project, environment, and whether the key is still enabled.Fix authentication; do not retry the same invalid key.
403 ForbiddenRequired permissions and resource targets; any quota details in the body.Adjust authorised access or resolve the quota restriction.
404 Not FoundEndpoint path, resource IDs, and whether a temporary result is still available.Verify the identifiers; do not automatically repeat the original operation.
429 Too Many RequestsRate, concurrent-work, or usage-limit information.Reduce demand and wait as appropriate for the limit.
500, 502, 503Service or upstream failure; any response details.Retry only if the operation is safe to repeat, using bounded backoff.

A connection timeout or network error may occur without an HTTP response. It does not establish whether the server received or completed the request.

Workflow success has more than one layer​

For a synchronous workflow run, inspect the JSON success field even when the HTTP status is 200. For example, this is a failed operation:

{
"success": false,
"statusCode": 400,
"err": {
"message": "Workflow execution failed."
}
}

The JSON statusCode describes the operation's result and can differ from the HTTP status.

For queued workflow runs, acceptance only means the run was queued. When polling:

  • Top-level success: true means the status lookup succeeded.
  • state: "completed" means execution returned a result; inspect output.success.
  • state: "failed" means the queued execution failed; inspect failedReason.
  • A completed result with output.success: false is also a workflow failure.

See Get run status for the response shape.

Understand the limit you reached​

Limits can apply to a project, an API key, or a particular service. Workflow starts and simultaneous runs have limits in addition to general API request rates. AI requests can also have their own rate limit. Creating more keys does not remove project-wide limits.

There is no single requests-per-minute value that describes every endpoint or project. Limits depend on the applicable policy and operation.

When supplied, these response codes help distinguish the cause:

  • RATE_QUOTA_EXCEEDED: a request or operation-start window has been exhausted. Wait for capacity in that window.
  • CONCURRENT_QUOTA_EXCEEDED: too much work is already in flight. Reduce concurrency and allow existing work to finish.
  • PERIOD_QUOTA_EXCEEDED: a usage allowance has been reached. A rapid retry loop will not resolve it.

A resource-capacity quota can instead produce a 403 response. Check its message and quota details rather than treating every 403 as a missing permission.

Some responses provide a Retry-After header or a JSON retryAfterMs value. Honour these when present; retryAfterMs is in milliseconds. Not every endpoint or limit response includes a retry hint.

Retry safely​

For read-only requests, use a limited number of retries with increasing delays and a small random variation (jitter). For example, wait roughly one second, then two, then four, while respecting any longer server-provided delay. Set a maximum delay and an overall deadline.

For operations that change data or start work, first ask whether repeating the request could repeat its effects:

  • Starting a workflow again can send another notification, create another record, or repeat another external action.
  • A timeout can happen after the server has accepted the request.
  • A workflow failure does not imply that earlier actions were rolled back.
  • If you already received an invocationId, poll that invocation instead of submitting another run.

The workflow-start endpoints do not provide an idempotency-key mechanism. If duplicate work would be harmful, design your application and workflow around a unique business-operation ID and an atomic check or uniqueness constraint before performing the action. Simply adding an ID to inputs does not enable deduplication by itself.

Polling and timeouts​

Poll queued runs on a measured interval, not in a tight loop. Polls are API requests and count towards rate limits. Back off on transient errors, stop on a terminal result, and give your caller an overall deadline.

Prefer queued runs for work that may outlast an HTTP request. A caller-side timeout does not guarantee cancellation. Keep the invocation ID and retrieve the result promptly: run status is temporary, not a permanent execution archive.

Persist important results in application storage. A later 404 can mean the run's status is no longer retained; it is not proof that the workflow never ran.

Troubleshoot without exposing secrets​

Record the method, path, HTTP status, timestamp, and any invocation ID, along with suitably redacted error details. Never log the Authorization header, and avoid logging sensitive inputs or outputs.

For workflow execution details, open Logs → API on the workflow. See Viewing workflow logs and Authentication and permissions.