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

# Protocol errors and safe retries

> Interpret refusals without weakening the original request or replaying an effect.

Error responses contain an `error` code. The HTTP status identifies the broad failure class; the code explains the specific refusal. Foreign resources are treated as unavailable without disclosing whether they exist.

| Status                   | Typical action                                                                                                       |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| `400`, `413`, `415`      | Correct invalid JSON, unsupported media or oversized material before submitting a new logical operation.             |
| `401`, `403`             | Check the credential, role or human-session requirements. Never fall back to a broader principal.                    |
| `404`, `410`             | The resource is inaccessible or private material has been deleted. A public digest is not permission to retrieve it. |
| `409`                    | Re-fetch status. The candidate, grant, identity, route or idempotency binding may no longer be usable.               |
| `429`                    | Respect quota pressure. New credentials do not reset stable principal or tenant quotas.                              |
| `5xx` or a lost response | The result may be unknown. Retry an idempotent operation with the original key, or reconcile its recorded state.     |

A request timeout does not prove that the server rejected the operation. A dispatch timeout does not prove that the effect did not happen. Keep those uncertainties separate: server retries use the same operation identity; an executor retains its durable launch fence and never repeats an uncertain effect.

Unsupported protocol or profile versions require an explicit compatibility decision. Do not remove required profiles or change purpose to make a refused request pass. Any material change needs a new request and, where required, fresh human review.

The [SDK error guide](/sdk/error-handling) shows how to handle these responses without automatic unsafe retries.