# Errors

What a failed call returns, what each status means and what to do next.

Every response, successful or not, uses the same envelope. A failed call has `data: null` and one or more entries in `errors`:

```json
{
  "data": null,
  "errors": [
    {
      "code": "conversion_failed",
      "message": "Requested conversion is not supported",
      "field": null
    }
  ],
  "meta": {
    "request_id": "req_2f8c1d4a9b3e",
    "timestamp": "2026-10-27T09:41:07.512Z",
    "version": "2026-03-26"
  }
}
```

`code` is the part to branch on: it is stable and machine-readable. `message` is written for people and may change. `field` is filled only for validation errors and names the body path that failed, for example `body -> content`.

| Status | Meaning | What to do |
| --- | --- | --- |
| `400` | The body matches the operation schema but the operation rejected it. `code` names the reason, for example `conversion_failed` or `invalid_base64`. | Fix the input. Retrying the same call cannot succeed. |
| `413` | The request is larger than the API accepts, 100 MB today, or it arrived without a `Content-Length` header (chunked bodies are refused). | Send a smaller body with a `Content-Length` header. |
| `422` | The body does not match the operation schema. One entry per problem, each with the code `validation_error` and the failing field. | Read every entry and fix the fields listed. |
| `500` | Something failed on the server. The envelope is the same and `errors` may be empty. | Retry later, and quote the `request_id` when you ask for help. |
| `501` | The operation is planned and not live yet. Nothing was executed. | Do not call it. Watch the [changelog](../changelog/). |

A request to a path or method that does not exist still answers the envelope, with the code `not_found` or `method_not_allowed`.

> [!tip] Keep the request_id
> Every failure carries a `request_id` in `meta`. It links the call to the server logs, so include it whenever you report a problem.

Bodies are JSON sent with `Content-Type: application/json`. A body that is not valid JSON answers `422` with the code `validation_error`.

---
Source: https://skillfulsardine.com/developers/api/errors/