> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spirii.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Errors
> The HTTP status codes the API returns, what they mean, and how to handle them.
The Spirii API uses standard HTTP status codes to signal the outcome of a request. A `2xx` status means the request succeeded. A `4xx` means something about the request needs fixing before it will work. A `5xx` means the request was valid, but Spirii couldn't complete it.
## Status codes
These are the codes you'll meet across the API. Each endpoint's reference page lists the specific codes it can return — a `404`, for instance, appears only where the request references a resource that might not exist.
| Status | Meaning | What to do |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
| `200` OK / `201` Created | The request succeeded | Continue |
| `400` Bad Request | The request was malformed or failed validation | Fix the request using the message in the response |
| `401` Unauthorized | The request isn't authenticated — the API key is missing, invalid, or expired | Check the `Authorization` header and your API key |
| `403` Forbidden | The request is authenticated but not allowed to perform this action | Check that your key has access to the resource |
| `404` Not Found | The resource — or a resource referenced in the request — doesn't exist | Check the ID or path |
| `409` Conflict | The request conflicts with the current state — the resource already exists, or is already in the state you're asking for | Check the current state; the change may already be applied |
| `422` Unprocessable Entity | The request was well-formed but broke a business rule | Fix the request using the message in the response |
| `500` Internal Server Error | Something failed on Spirii's side | Retry with backoff; if it persists, contact support |
| `502` Bad Gateway | A transient upstream error | Retry with backoff |
`401` and `403` both signal an access problem: `401` when a request isn't authenticated, `403` when it's authenticated but not permitted. Usage isn't fully consistent across the API — some endpoints return `403` for an authentication failure — so treat either as an access issue, check your key and its permissions, and read the endpoint's reference for the codes it returns. See [Authentication](/developers/authentication) for how to send the key correctly.
## Error responses
An error response carries the status code and a human-readable message describing what went wrong.
Read the **status code** to decide what your integration does next, and surface the **message** to whoever is operating the integration. Treat the message as descriptive text for a person, not a stable field to branch on in code — the status code is the contract.
## Handling errors
How you respond depends on the class of error:
* **`4xx` — fix the request.** A validation error, a missing resource, or an auth problem won't resolve on its own. Don't retry the same request unchanged; correct it first. A `409` is the exception: the request may be valid but the resource is already in the target state, so read the current state before deciding whether to retry.
* **`5xx` — retry with backoff.** A `500` or `502` is usually transient. Retry with exponential backoff and a ceiling on attempts rather than looping immediately.
* **Rate limiting.** Requests beyond the limit are rejected. Back off and retry, and see [Rate limits](/developers/rate-limits) for the current limit and how to stay under it.
Retrying is safe for reads. For writes, a `5xx` doesn't tell you whether the change applied — check the resource's state before retrying a create or update, so you don't duplicate it.
## Related
Authenticate your requests correctly to avoid `401` and `403` responses.
Stay within the request limit.
The status codes each endpoint can return.