Source: https://www.puesto.dev/docs/errors
Markdown source: https://www.puesto.dev/docs/errors.md
Description: The RFC 7807 problem+json error format, validation error details, and status codes.

# Errors



Errors are returned as [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807)
`application/problem+json` documents. The response `Content-Type` is
`application/problem+json` and the body always includes at least `type`,
`title`, and `status`.

## Problem shape [#problem-shape]

```json
{
  "type": "about:blank",
  "title": "Invalid query parameters",
  "status": 400,
  "detail": "limit: Expected number, received string"
}
```

| Field    | Type    | Description                                               |
| -------- | ------- | --------------------------------------------------------- |
| `type`   | string  | A URI reference identifying the problem type.             |
| `title`  | string  | A short, human-readable summary of the problem.           |
| `status` | integer | The HTTP status code.                                     |
| `detail` | string  | A human-readable explanation specific to this occurrence. |
| `errors` | array   | Per-field validation errors, when applicable (see below). |

## Validation errors [#validation-errors]

When a request fails validation, the problem includes an `errors` array — one
entry per offending field:

```json
{
  "type": "about:blank",
  "title": "Invalid query parameters",
  "status": 400,
  "detail": "limit: Expected number, received string; country: Too many items",
  "errors": [
    { "field": "limit", "message": "Expected number, received string" },
    { "field": "country", "message": "Too many items" }
  ]
}
```

Each entry has a `field` (the offending field path) and a `message` (what was
wrong with it).

## Status codes [#status-codes]

| Status                      | Meaning                                                                                                             |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`           | Invalid query parameters or a malformed pagination cursor. Includes `errors[]` for field-level validation failures. |
| `401 Unauthorized`          | Missing or invalid API key. See [Authentication](/docs/authentication).                                             |
| `404 Not Found`             | No job exists with the requested id.                                                                                |
| `429 Too Many Requests`     | Per-account rate limit exceeded. Includes a `Retry-After` header. See [Rate limits](/docs/rate-limits).             |
| `500 Internal Server Error` | An unexpected error occurred on our side.                                                                           |