> ## Documentation Index
> Fetch the complete documentation index at: https://docs.infragrid.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and retries

> Handle API errors, request IDs, retryable responses, and terminal run failures.

Transport failures and run failures are separate. An HTTP error means the API request failed. A successful `202` or `200` can still describe a run that later reaches `failed`.

## HTTP status codes

| Status | Meaning                                             | Client action                             |
| ------ | --------------------------------------------------- | ----------------------------------------- |
| `400`  | Malformed request                                   | Fix the request                           |
| `401`  | Missing, invalid, expired, or revoked credential    | Replace the credential                    |
| `402`  | Workspace has insufficient cloud credits            | Add credits or stop dispatch              |
| `403`  | Credential lacks the required scope                 | Replace it with a correctly scoped key    |
| `404`  | Resource is absent or not visible to this workspace | Verify the ID and workspace               |
| `409`  | State, concurrency, or idempotency conflict         | Follow the response; do not blindly retry |
| `422`  | Input or published Blueprint contract is invalid    | Fix the payload                           |
| `429`  | Rate or concurrency limit                           | Honor `Retry-After` and back off          |
| `5xx`  | Transient platform failure                          | Retry safe requests with bounded backoff  |

Error bodies have a `detail` field. When present, the `X-Request-ID` response header correlates the request with platform logs.

## Retry policy

The SDKs retry transient connection failures, `408`, `429`, and `5xx` responses for safe `GET` requests. The default is two retries with bounded exponential backoff.

Mutation requests are not retried unless run creation includes an [idempotency key](/production/idempotency). Cancellation is idempotent but the SDK sends it once.

<Warning>
  Do not retry a create request automatically unless it carries the same stable idempotency key and the same body.
</Warning>

## SDK errors

Both SDKs expose these subclasses of `InfragridError`:

* `AuthenticationError`
* `PermissionDeniedError`
* `NotFoundError`
* `RateLimitError`
* `ServerError`
* `APIConnectionError`
* `APITimeoutError`

Errors preserve `status`, a bounded response `body`, and `requestId` / `request_id` when available.

## Terminal run failures

A `failed` run includes a display-safe `error_code` and `error_message`. Do not infer success from an HTTP `200` alone—always inspect the run status.

When opening a support case, include:

* run ID
* request ID, when available
* SDK name and version
* terminal status
* `error_code`

Never include the API key, website credentials, cookies, or extracted personal data.

## Timeouts and cancellation

SDK wait helpers enforce an overall client-side deadline. A wait timeout does not automatically prove the cloud run stopped. Retrieve the run again or call the cancel endpoint if the business operation should end.


## Related topics

- [TypeScript SDK](/sdks/typescript.md)
- [API overview](/reference/overview.md)
- [Security model](/security.md)
- [Python SDK](/sdks/python.md)
- [Limits](/production/limits.md)