# Errors

> **Section:** [Introduction](https://docs.editsquare.com/api.md)
> **Related:** [Authentication](https://docs.editsquare.com/api/authentication.md) · [Pagination](https://docs.editsquare.com/api/pagination.md) · [Renders](https://docs.editsquare.com/api/renders.md) · [Webhooks](https://docs.editsquare.com/api/webhooks.md)
> **Also:** [HTML version](https://docs.editsquare.com/api/errors) · [Docs index](https://docs.editsquare.com/llms.txt)

---
Edit Square uses conventional HTTP response codes to indicate whether an API
request succeeded or failed. In general:

- Codes in the `2xx` range indicate success.
- Codes in the `4xx` range indicate a problem with the request itself - a
  missing parameter, an invalid API key, an ID that doesn't exist.
- Codes in the `5xx` range indicate an error on our side. These are rare, and
  they are the only ones worth retrying unchanged.

## HTTP status codes

| Code | | Meaning |
| --- | --- | --- |
| `200` | OK | Everything worked as expected. |
| `201` | Created | The entity was created. |
| `400` | Bad Request | The request was understood but could not be carried out. |
| `401` | Unauthorized | No API key was provided, or the key is not valid. |
| `402` | Payment Required | The team has run out of credits. |
| `403` | Forbidden | The key is valid but does not have access to this resource. |
| `404` | Not Found | The resource doesn't exist, or your key can't access it. The API deliberately doesn't distinguish between the two. |
| `422` | Unprocessable Content | The request failed validation. The response lists the fields that failed. |
| `500` | Server Error | Something went wrong on our end. |

## The error object

Every error response is a JSON object containing an `error` field, whose
value is a human-readable sentence describing what went wrong. It is written
for a developer reading a log, not for display to an end user. For everything
except validation failures, `error` is the only field in the object:

```json
{ "error": "Render not found" }
```

### Validation errors

A `422` extends the object with two extra fields: a `message` string that
summarises the failure on a single line (the problem itself when there is only
one, a count when there are several), and a `details` array with one entry for
each field that failed:

```json
{
  "error": "Validation failed",
  "details": [
    {
      "field": "project_id",
      "message": "project_id: Project ID is required",
      "code": "too_small"
    }
  ],
  "message": "project_id: Project ID is required"
}
```

Each entry in `details` has:

| Attribute | | Description |
| --- | --- | --- |
| `field` | string | The name of the parameter that failed, using dot notation for nested parameters. Set to `unknown` when the failure can't be attributed to a single field. |
| `message` | string | A description of what is wrong with the value, prefixed with the field name. |
| `code` | string | The name of the validation rule that failed - `too_small`, `invalid_type`, and so on. |

`field` is what makes a `422` worth surfacing to users: it identifies the
parameter that needs fixing, so a form can highlight the offending input
instead of showing the raw response.

## Retrying

`500` responses and network failures are worth retrying with backoff. `401`,
`403`, `404` and `422` are not - they describe a problem with the request, and
the same request will fail the same way. A `402` means the team needs more
credits before anything else will work.