> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pgw.sipmicro.services/llms.txt
> Use this file to discover all available pages before exploring further.

# Handle API errors

> Read the error body that the admin API returns, and look up the status codes that it uses.

When a request fails, the API answers with an HTTP status code and a JSON body with one field, `error`, which says what went wrong. A request with a missing or wrong API key gets the following answer.

```text theme={null}
HTTP/1.1 401 Unauthorized
Cache-Control: no-store
Content-Type: application/json
Www-Authenticate: Bearer
Date: Sun, 15 Nov 2026 23:52:45 GMT
Content-Length: 39

{"error":"missing or unknown API key"}
```

A `limit` outside its range gets `400`.

```json theme={null}
{"error":"limit must be from 1 to 1000"}
```

A message can name a field, such as `unknown field "bogus"`, but never repeats a value that you sent, so an error can't echo a secret.

## Status codes

| Status | When |
| - | - |
| `200 OK` | The request worked, and the body holds the result. |
| `201 Created` | pgw created the tenant, app record, upstream, or user. |
| `204 No Content` | pgw deleted the record or lifted the ban. The body is empty. |
| `400 Bad Request` | The body isn't one JSON object, has a field that the endpoint doesn't know, is larger than the limit, or holds a value that isn't valid. Or a query parameter, such as `limit` or `after`, isn't valid. |
| `401 Unauthorized` | The API key or the bootstrap token is missing or wrong. |
| `403 Forbidden` | The endpoint needs the bootstrap token, and pgw started without `PGW_BOOTSTRAP_TOKEN`. |
| `404 Not Found` | The path is unknown, or the tenant has no record with the ID or key in the path. |
| `405 Method Not Allowed` | The path doesn't serve the method. The `Allow` header lists the methods that it serves. |
| `409 Conflict` | The request conflicts with existing records, for example an app record with the same platform and bundle ID, a host or domain that another upstream serves, an upstream that bindings still use, or a second bootstrap. |
| `422 Unprocessable Entity` | `POST /api/v1/tls/reload` found certificate files that aren't a valid pair. pgw keeps the old certificate. |
| `429 Too Many Requests` | `POST /api/v1/bindings/{key}/test-push` found that the device reached `call_push_rate_per_binding`. |
| `500 Internal Server Error` | pgw couldn't finish the request, for example because the database didn't answer, including a request whose API key pgw couldn't check. The body is `{"error":"internal error"}`, and pgw logs the cause as `api request failed`. |

Each endpoint page lists the status codes that the endpoint returns.

## Next steps

> [card] [Page through lists](https://docs.pgw.sipmicro.services/api/pagination.md)
>
> Read long lists of bindings and users with `limit` and `after`.

> [card] [Read the logs](https://docs.pgw.sipmicro.services/logs.md)
>
> Find the cause of a `500` in the `api request failed` line.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.