---
title: "Errors"
description: "The JSON shape of every pkgplane API error, including validation errors."
---

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

# Errors

Every error from the pkgplane API is JSON with an `error` object:

```json
{ "error": { "message": "API key not found" } }
```

| Field                    | Type                 | Description                                              |
| ------------------------ | -------------------- | -------------------------------------------------------- |
| `error.message`          | string               | What went wrong, written for a person to read            |
| `error.issues`           | array                | Only on `422`: one entry per invalid field               |
| `error.issues[].path`    | (string \| number)[] | Where the field is, such as `["name"]` or `["items", 0]` |
| `error.issues[].message` | string               | What's wrong with it                                     |

Match on the HTTP status code, not on `message`: messages can be reworded.

## Validation errors

A request whose body, path or query doesn't match the endpoint's schema gets `422 Unprocessable
Content` and lists each problem:

```json
{
  "error": {
    "message": "Validation failed",
    "issues": [{ "path": ["expiresInDays"], "message": "Too big: expected number to be <=365" }]
  }
}
```

## Status codes

| Status | Meaning                                                                          |
| ------ | -------------------------------------------------------------------------------- |
| `401`  | Not authenticated. See [Authentication](https://pkgplane-docs.richaisolutions.com/reference/authentication/#status-codes) |
| `403`  | Authenticated, but not allowed                                                   |
| `404`  | No such endpoint, or no such resource in your account                            |
| `409`  | Conflicts with what exists, such as a 26th API key                               |
| `422`  | Invalid request. See [Validation errors](#validation-errors)                     |
| `429`  | Rate limited. Retry after `Retry-After` seconds                                  |
| `500`  | A fault in pkgplane. The message is always `Internal server error`               |
| `503`  | From `GET /api/health` only: the database is unavailable                         |

Source: https://pkgplane-docs.richaisolutions.com/reference/errors/index.mdx