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, and a 409 needs idempotency conflict handling. Don't treat every non-200 response as permission to run a new create.