Developers
Understand errors and retries
Know when to fix the request, sign in or check saved work.
| Response | Meaning | Next step |
|---|---|---|
| 400 | The request is malformed or missing required context | Check the example and fields |
| 401 | Sign-in/token failed | Check expiry, issuer, audience and required scope |
| 403 | You are signed in but cannot do this | Check workspace, role and app grant |
| 404 | No accessible record at that ID | Confirm the ID and account; another user's record may intentionally appear missing |
| 409 | The operation conflicts with current state | Re-read the run; for example, wait for a stop before resuming |
| 413 | Input is too large | Use the supported upload or smaller request |
| 422 | A field or scientific request is invalid | Read the validation details |
| 429 | Too many requests | Respect the supplied retry delay |
| 502/503 | A required service is unavailable | Wait, check status and retry a read carefully |
Reads can use bounded retries with backoff. Do not blindly retry a start, resume, decision or external write after a timeout. First inspect saved work to learn whether it happened. Reuse an operation's documented idempotency identifier where supported. An arbitrary Idempotency-Key header is not proof that an endpoint implements deduplication.
Keep the run ID and a sanitized error in your logs. Do not log tokens or full private scientific inputs by default.