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

# Errors and retries

> Diagnose failed requests and decide when an operation can be retried.

Start with the HTTP status, error body, and request identifier returned by the operation. Error envelopes vary across MKA1 services; use the endpoint’s documented schema rather than assuming every error has the same fields.

## Classify the failure

| Response                     | What to check                                                       | Retry?                                            |
| ---------------------------- | ------------------------------------------------------------------- | ------------------------------------------------- |
| `400`                        | Required fields, types, and supported options                       | Correct the request first.                        |
| `401`                        | API key, token expiry, and gateway address                          | Correct authentication first.                     |
| `403`                        | Key scopes, resource permissions, or an exhausted budget            | Resolve the cause first.                          |
| `404`                        | Resource ID and the identity that can access it                     | Verify the resource and caller first.             |
| `409`                        | Current resource state or a conflicting operation                   | Read the resource and follow its lifecycle rules. |
| `429`                        | Rate limit for the caller                                           | Wait before retrying.                             |
| `5xx` or a transport failure | Service availability and whether a write may already have completed | Retry only when safe for that operation.          |

## Back off between attempts

For a retryable failure, wait progressively longer between attempts, add jitter so concurrent clients do not retry together, and bound both the attempt count and total time. Honor `Retry-After` when an endpoint returns it.

Check the selected SDK’s retry settings before adding another retry loop. Nested retry policies can multiply the number of requests.

## Avoid duplicate writes

A timeout does not prove the server rejected the request. Before repeating a create operation, determine whether the resource was created.

Where an endpoint supports an idempotency key, reuse the same key only for an identical retry. Generate a new key for a new operation. Do not assume that an idempotency header is supported by every API.

For Compute, use the examples in [Run a fine-tune job](/docs/compute-fine-tune-job) and [Deploy a model server](/docs/compute-deployment).

## Handle streaming and background work

A streaming connection can end after delivering partial output. Avoid treating the partial output as a completed result. Follow the status and retrieval mechanisms described in [Background responses](/docs/background-responses).

## Separate refusals from transport errors

A [guardrail](/docs/guardrails) can return a refusal in a successful HTTP response. Inspect the output; retrying the same blocked request is not a transport-recovery strategy.

## Investigate a failure

* Confirm the gateway URL and caller identity.
* Record the request identifier, resource ID, status, and error body without logging credentials.
* Check [Rate limits](/docs/rate-limiting), [Budgets](/docs/budgets), and [Resource permissions](/docs/authorization) as appropriate.
* Use [CLI debugging](/docs/cli/diagnostics) to inspect request construction.
* Correlate the request with [Usage and auditing](/docs/usage-auditing).