API

# Errors

Every error status and code the API returns.

Errors have a JSON body with a stable `code` and a readable `message`:

error body

```
{"error": {"code": "not_found", "message": "environment has no published version"}}
```

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `invalid_*` | A malformed parameter or body. `invalid_query_string`: the URL's query isn't valid encoding (write a literal `%` as `%25`). |
| 401 | `unauthorized` | Missing or invalid credentials. |
| 401 | `key_expired` | The API key has passed its expiry date. |
| 403 | `forbidden` | A publishable key tried to write. |
| 403 | `key_scope_denied` | The key is limited to other bins or environments, or expires and so can't manage keys. |
| 403 | `production_admin_only` | Only administrators change production; members work in development and staging. |
| 403 | `key_creator_not_admin` | The key's creator is no longer an administrator, so it can't change production or manage keys. |
| 403 | `owner_only` | Only the organization's owner manages billing, deletes the organization or hands it over. |
| 403 | `owner_protected` | The owner can't be removed or have their role changed; the owner hands the organization over instead. |
| 422 | `owner_cannot_leave` | The owner can't leave; make someone else the owner first, or delete the organization. |
| 403 | `read_only_keys_require_pro` | Publishable (read-only) keys are part of Pro; on Free every bin is public. |
| 403 | `key_unattributed` | The key predates attribution, so it can't create or rotate keys. |
| 404 | `not_found` | No such bin or version, or nothing published in the environment. |
| 404 | `version_pruned` | The rollback target is older than the versions your plan keeps. |
| 409 | `bin_exists` | The bin id is taken. |
| 409 | `key_expired` | An expired key can't be rotated; create a new one. |
| 413 | `payload_too_large` | The payload is over your plan's size limit. |
| 413 | `schema_too_large` | A bin's JSON Schema can be at most 64 KiB. |
| 422 | `schema_validation_failed` | The payload fails the schema. |
| 422 | `schema_too_complex` | Validating this payload would take more than 3 million subschema checks. Simplify repeated `$ref`s or nested `allOf`/`anyOf`/`oneOf`. |
| 422 | `query_*` | The jq filter is invalid, failed at runtime, too slow, or its result too large. `query_empty`: it produced no output (end it with `// {}` to always return a value). |
| 403 | `over_plan_limits` | The organization has more bins or seats than its plan allows (after moving to Free), so its bins are read-only. Delete bins or remove members and invites, or upgrade. |
| 422 | `bin_limit_reached`, `seat_limit_reached` | Your plan's bin or seat limit is reached. |
| 429 | `rate_limited` | Too many requests from your IP, key, account or organization; retry after `Retry-After` seconds. |
| 429 | `daily_bin_limit_reached` | Your organization created its plan's number of bins in the last 24 hours; deleting bins doesn't reset it. |
| 429 | `delay_limited` | Too many `?delay=` reads from your IP at once (4). |
| 429 | `query_busy` | Too many jq queries at once; retry after `Retry-After`. |
| 503 | `query_memory` | The jq filter needed more memory than a query may use. |
| 503 | `query_unavailable` | The query engine could not start; retry shortly. |
| 503 | `write_busy` | Too many writes in progress on the server; retry after `Retry-After`. |
| 503 | `delay_busy` | Too many `?delay=` reads on the server at once. |
| 507 | `org_storage_exceeded` | Your organization's storage limit is reached. Delete bins or environments, or upgrade. |
| 507 | `storage_quota_exceeded` | The server's storage limit is reached. Reads and deletes still work. |

Last updated 10 November 2026
