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

# Errors & rate limits

> How the Sparqle API reports failures and throttles requests.

The Sparqle API uses conventional HTTP status codes. `2xx` means success, `4xx`
means the request was rejected (usually something you can fix), and `5xx` means
a problem on Sparqle's side.

## Status codes

| Code          | Meaning                                                            |
| ------------- | ------------------------------------------------------------------ |
| `200` / `201` | Success.                                                           |
| `400`         | Validation error — a field is missing, malformed, or out of range. |
| `401`         | Missing or invalid API key.                                        |
| `403`         | The key isn't allowed to act on this `locationId` or order.        |
| `404`         | The order, label, or resource doesn't exist.                       |
| `429`         | Too many requests — you've hit the rate limit.                     |
| `500`         | Unexpected error on Sparqle's side.                                |

## Validation errors

Request bodies are validated field by field. A `400` response lists what failed,
so you can surface the specific problem:

```json theme={null}
{
  "statusCode": 400,
  "message": [
    "deliveryName should not be empty",
    "deliveryAddress.postalCode must be a string"
  ],
  "error": "Bad Request"
}
```

Common causes:

* Missing a required field (`locationId`)

## Rate limits

Public tracking endpoints are throttled. If you exceed the limit you'll get a
`429` — back off and retry with exponential delay. If you expect sustained high
volume on the order endpoints, coordinate limits with your Sparqle contact.

<Tip>
  Build retries with exponential backoff for `429` and `5xx` responses, and
  treat `4xx` (except `429`) as permanent — retrying won't help until you fix the
  request.
</Tip>