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

# Errors

> How the Sevalla API reports errors, including the error object shape and HTTP status codes.

The Sevalla API uses standard HTTP status codes and returns a consistent JSON error object when something goes wrong.

## Error object

Every error response has this shape:

```json theme={null}
{
  "message": "Unauthorized",
  "status": 401,
  "data": {
    "code": "err-abc-123",
    "message": "If you need assistance, please contact support."
  }
}
```

| Field          | Type    | Description                                                      |
| -------------- | ------- | ---------------------------------------------------------------- |
| `message`      | string  | Short description of the error.                                  |
| `status`       | integer | HTTP status code.                                                |
| `data.code`    | string  | Error tracking identifier. Include this when contacting support. |
| `data.message` | string  | Additional context or instructions for resolving the error.      |

<Note>The `data` field may not be present on all error responses. Always check for it before accessing nested fields.</Note>

## HTTP status codes

| Code  | Meaning                                                                               |
| ----- | ------------------------------------------------------------------------------------- |
| `200` | Success. The request completed and returned data.                                     |
| `201` | Created. A new resource was created.                                                  |
| `204` | No content. The request succeeded but there's nothing to return (common for deletes). |
| `400` | Bad request. The request body or parameters are invalid.                              |
| `401` | Unauthorized. Missing or invalid API key.                                             |
| `403` | Forbidden. The API key doesn't have permission for this action.                       |
| `404` | Not found. The resource doesn't exist or you don't have access to it.                 |
| `422` | Unprocessable entity. The request was well-formed but failed validation.              |
| `429` | Too many requests. You're being rate limited.                                         |
| `500` | Internal server error. Something went wrong on our end.                               |

## Handling errors

<Steps>
  <Step title="Check the status code">
    Use the HTTP status code to determine the category of error. 4xx means something is wrong with your request. 5xx means something went wrong on our side.
  </Step>

  <Step title="Read the message">
    The `message` field tells you what went wrong. The `data.message` field, when present, gives you specific guidance on how to fix it.
  </Step>

  <Step title="Save the error code">
    If the response includes `data.code`, save it. Support can use this to look up exactly what happened.
  </Step>
</Steps>

<Warning>Don't retry `4xx` errors without changing the request. They will keep failing. Retry `5xx` errors with exponential backoff.</Warning>