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

# Errors

> How the Stell API reports errors and what each status code means

The API uses conventional HTTP status codes: `2xx` for success, `4xx` for something wrong with the request, and `5xx` for a problem on Stell's side.

## Error response format

Every error returns a JSON body with the same shape:

```json theme={null}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "details": {}
  },
  "requestId": "01JXAMPLE0000000000000000"
}
```

* `error.code`: a machine-readable code your integration can branch on.
* `error.message`: a human-readable explanation of what went wrong.
* `error.details`: additional context when available, such as which field failed validation.
* `requestId`: a unique identifier for the request. Include it when you [contact support](/support/contact) about a failed call. It lets us find the exact request in our logs.

## Status codes

| Status                      | Code               | Meaning                                                                                                                                                                                             |
| --------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200 OK`                    | n/a                | The request succeeded.                                                                                                                                                                              |
| `201 Created`               | n/a                | The resource was created. Returned by create endpoints such as issuing a pass.                                                                                                                      |
| `204 No Content`            | n/a                | The request succeeded and there is nothing to return, typical for deletes.                                                                                                                          |
| `400 Bad Request`           | `BAD_REQUEST`      | The request is malformed — missing required fields, wrong types, invalid JSON.                                                                                                                      |
| `400 Bad Request`           | `VALIDATION_ERROR` | A field failed validation against its own rules — an unrecognized field, a phone number not in E.164 format, an enum value outside the accepted set. Check `error.details` for the offending field. |
| `401 Unauthorized`          | `UNAUTHORIZED`     | The API key is missing, invalid, expired, or revoked. See [Authentication](/api-reference/authentication).                                                                                          |
| `403 Forbidden`             | `FORBIDDEN`        | The key is valid but the resource belongs to another company.                                                                                                                                       |
| `404 Not Found`             | `NOT_FOUND`        | The resource doesn't exist, often because of a mistyped or stale ID.                                                                                                                                |
| `409 Conflict`              | `CONFLICT`         | The request conflicts with the resource's current state — for example, updating a voided or expired pass, or deleting a merchant that still has stores. `error.message` names the specific rule.    |
| `429 Too Many Requests`     | n/a                | You're sending requests faster than the API allows. Back off and retry with a delay.                                                                                                                |
| `500 Internal Server Error` | `INTERNAL_ERROR`   | Something went wrong on Stell's side. Retry with backoff; if it persists, contact support with the `requestId`.                                                                                     |
| `503 Service Unavailable`   | n/a                | The API is temporarily unavailable. Retry with backoff.                                                                                                                                             |

## Handle errors well

* Branch on `error.code`, not on `error.message`. Messages can change, codes won't.
* Retry `5xx` and `429` responses with exponential backoff. Don't retry `4xx` responses unchanged; fix the request first.
* Log the `requestId` for every failed call so support conversations start with the right context.