> ## 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.

# Stell API errors and status codes

> How the Stell API reports errors: the JSON error shape, status codes and error codes, and which errors are safe to retry.

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, such as 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.