> Documentation index: https://beezr.io/developers/api/llms.txt

# Errors

## Read the error envelope

```json
{"success":false,"error":{"code":"MODULE_NOT_FOUND","message":"...","details":null}}
```

`success: false` marks a failed JSON response. `error.code` is the machine-readable reason; `error.message` explains what happened. `details` is usually absent. Idempotency conflicts include operation details. A successful file download returns bytes instead of this envelope.

## Error codes

| HTTP | Code | Meaning | How to fix |
| --- | --- | --- | --- |
| 400 | `MISSING_REQUIRED_FIELD` | A required body field is missing | Send the required module, data, ids or download fields. |
| 400 | `INVALID_DATA` | No data fields match the module | Copy field System names from the Designer. |
| 400 | `INVALID_FILTER` | Invalid filter field or operator | Use module field names and a supported operator. |
| 400 | `INVALID_SORT` | No valid sort field | Use a field of the module. |
| 400 | `INVALID_IDEMPOTENCY_KEY` | Bad idempotency header | Send one key: 1–128 visible ASCII characters. |
| 400 | `KEY_FIELD_UNRESOLVED` | The module has no key field | Check the module key field in the Designer. |
| 401 | `AUTHENTICATION_FAILED` | Missing, invalid or paused key | Check the server environment and X-API-Key header. |
| 404 | `MODULE_NOT_FOUND` | Wrong module table name | Copy the table name under the module card name. |
| 404 | `NOT_FOUND` | No record with that id | Check the record id used with get. |
| 404 | `CONTENT_NOT_FOUND` | File not attached or bytes unavailable | Use the reference module and the record id. |
| 409 | `IDEMPOTENCY_KEY_REUSED` | Same key, different body | Keep the body unchanged; use a new key for new work. |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | First call still running within 120 seconds | Wait Retry-After: 2 before checking again. |
| 409 | `IDEMPOTENCY_RESULT_UNKNOWN` | The first outcome is unknown | Reconcile the record before starting new work. |
| 413 | `PAYLOAD_TOO_LARGE` | More than 100 bulk items | Split the batch into at most 100 items. |
| 400 | `INVALID_CONTENT_PAYLOAD` | A file field got something other than a file object | Send {"fileName", "data"}; multi-file fields take an array of them. |
| 400 | `CONTENT_DECODE_FAILED` | File data is not valid base64 | Base64-encode the file bytes and send them as data. |
| 400 · 413 | `CONTENT_TOO_LARGE` | File over 10 MB (400 on upload, 413 on download) | Keep each file within 10 MB. The message names the field. |
| 429 | `RATE_LIMIT_EXCEEDED` | A rate limit was exceeded | Wait Retry-After seconds; use the read reset header where applicable. |
| 429 | `TOO_MANY_CONCURRENT_REQUESTS` | Too many concurrent calls | Keep at most 2 in flight; wait Retry-After: 1. |
| 429 | `MONTHLY_QUOTA_EXCEEDED` | Monthly allowance passed 110% | Stop retrying until the 1st. |
| 409 · 422 · 500 | `CREATE_FAILED` | Refused or failed; error.message says why | 409: a record with this key already exists. 422: a workspace rule or plan limit refused it; fix the data, don't retry as is. 500: server problem; retry once. |
| 409 · 422 · 500 | `UPDATE_FAILED` | Refused or failed; error.message says why | 409: a record with this key already exists. 422: a workspace rule or plan limit refused it; fix the data, don't retry as is. 500: server problem; retry once. |
| 409 · 422 · 500 | `DELETE_FAILED` | Refused or failed; error.message says why | 409: a record with this key already exists. 422: a workspace rule or plan limit refused it; fix the data, don't retry as is. 500: server problem; retry once. |
| 500 | `QUERY_FAILED` | The read failed | Retry once; contact us if it persists. |
| 500 | `GET_FAILED` | The read failed | Retry once; contact us if it persists. |
| 500 | `FIELD_LOAD_FAILED` | Server problem | Retry later. |
| 500 | `INTERNAL_ERROR` | Server problem | Retry later. |

## Fix the cause before repeating a write

Unknown field names in `data` are ignored. `INVALID_DATA` means none matched. Business rules can return `CREATE_FAILED`, `UPDATE_FAILED` or `DELETE_FAILED` with HTTP 500 today; read the message before repeating the operation.

A 429 needs [limit-specific handling](/developers/api/limits/), and a 409 needs [idempotency conflict handling](/developers/api/idempotency/). Don't treat every non-200 response as permission to run a new create.