# Errors

Every error is a JSON body with a `message`, and validation errors add an `errors` map. Send
`Accept: application/json` on every request so errors always come back as JSON.

| Status | Meaning | What to do |
|--------|---------|------------|
| [400](#400-bad-request) | A filter, sort or include the endpoint doesn't allow | Use one of the values the message lists |
| [401](#401-unauthorized) | Missing, invalid or expired token | Check the `Authorization` header, or create a new token |
| [403](#403-forbidden) | The token lacks the permission, or the account can't see the record | Use a token with the right permission and scope |
| [404](#404-not-found) | No such record in your organization | Check the id |
| [409](#409-conflict) | The record can't be changed in its current state | Read the message, which says why |
| [422](#422-unprocessable-entity) | The request body or parameters failed validation | Fix the fields named in `errors` |
| [429](#429-too-many-requests) | Over the rate limit | Wait for `Retry-After` seconds |
| [503](#503-service-unavailable) | Order history is busy | Retry after `Retry-After` seconds |

## 400 Bad Request

You asked a collection for a filter, sort or include it doesn't support. The message names the
values it does allow:

```json
{
  "message": "Requested filter(s) `status` are not allowed. Allowed filter(s) are `external_id`."
}
```

[Querying collections](https://franchisesee.com/docs/api/querying.md#what-each-collection-accepts) lists what each collection
accepts.

## 401 Unauthorized

The request carried no token, or the token is invalid, expired or deleted:

```json
{
  "message": "Unauthenticated."
}
```

Common causes:

- The `Authorization` header is missing.
- The header doesn't start with `Bearer ` followed by the token.
- The token has expired. Franchisee tokens always expire; HQ tokens expire unless they were
  created to never expire.
- The token was deleted, or (for a franchisee token) the brand turned off franchisee tokens.

## 403 Forbidden

The token is valid, but it isn't allowed to do this. Either the token lacks the permission the
endpoint needs:

```json
{
  "message": "This API token does not have the 'create' ability."
}
```

or the account that owns the token isn't allowed to act on this record. A franchisee asking for a
location outside their own stores gets a `403`, as does any account without the role permission
for the action. See [Token permissions](https://franchisesee.com/docs/api/getting-started.md#token-permissions).

## 404 Not Found

No record with that id exists in your organization:

```json
{
  "message": "Record not found."
}
```

Records in other organizations are never visible, so they also return `404`.

## 409 Conflict

The record exists, but its current state doesn't allow the change. For example, a location can be
deleted only once it is pending, or deactivated with no history left to keep:

```json
{
  "message": "Cannot delete an active location. Deactivate it first."
}
```

The message always says why. For locations, the `is_deletable` and `deletable_on` fields tell you
ahead of time whether, and from when, a delete will succeed.

## 422 Unprocessable Entity

A field failed validation. `message` summarizes the first problem, and `errors` lists every
problem by field:

```json
{
  "message": "The name field is required.",
  "errors": {
    "name": ["The name field is required."]
  }
}
```

## 429 Too Many Requests

The `/api/v1` endpoints allow 60 requests per minute per user, shared by all of that user's
tokens. Over that, the API answers `429`
until the window resets. The `Retry-After` header says how many seconds to wait.

Back off and retry after that many seconds. To stay under the limit, ask for larger pages
(`page[size]=100`) and cache data that changes rarely.

## 503 Service Unavailable

The orders endpoints read check-level history, which can be briefly busy:

```json
{
  "message": "Order history is busy; try again in a moment."
}
```

Retry after the number of seconds in the `Retry-After` header.
