API 4.4.0 adds structured information to newly returned errors. Existing HTTP status choices and the string error field remain. Historical ingestion responses replay unchanged, so integrations must also accept older error bodies.
Read an error
| Field | How to use it |
|---|---|
code | Stable failure reason for programmatic handling. Tolerate unknown codes. |
error | Human-readable summary; do not parse this text for control flow. |
message, details | Legacy explanation when present. details can be a string or an array of strings. |
issues | Up to 50 problems with location, path, code, message, and optional expected constraints. |
context | Relevant resource or business facts. Monetary adjustment values use normalized decimal strings. |
action | Recovery instructions. On an error this is guidance text; success responses use actions such as created or unchanged. |
retryable | Whether automatically repeating this operation is appropriate. false does not mean the service can never recover. |
error_id | Failure identifier. A recorded rejection keeps this same value on replay. |
event_id | Present when an ingestion event exists; absent for validation before reservation or rolled-back work. |
Newly serialized errors include error, code, action, retryable, and error_id. Other fields are conditional. Accept additional fields so an expanded response does not break your integration.
Each issue has a location of body, query, path, or header. Its path is a JSON Pointer relative to that input: /data/change_date identifies a body field, /limit a query parameter, and /items/3/idempotency_key the key of the fourth batch item. An empty path identifies the whole input. JSON Pointer escapes ~ as ~0 and / as ~1 in property names.
Issue codes distinguish missing, null, wrong-type, unknown-field, invalid-value, range, and business-reference problems. They are separate from the top-level error code. Use expected, when present, for allowed values, formats, or bounds. A shortened issue list is flagged by issues_truncated or context.issues_truncated.
Example: an adjustment needs a date and reason
Reducing a stored disbursement's expected margin requires change_date and change_reason. Omitting them returns HTTP 400 with the following fields; the response can also include legacy details and context explaining the adjustment:
{
"status": "error",
"error": "Payload validation failed",
"code": "DISBURSEMENT_CHANGE_METADATA_REQUIRED",
"issues": [
{
"location": "body",
"path": "/data/change_date",
"code": "REQUIRED",
"message": "Provide the effective date of this adjustment.",
"expected": "YYYY-MM-DD or a supported ISO 8601 timestamp"
},
{
"location": "body",
"path": "/data/change_reason",
"code": "REQUIRED",
"message": "Provide a nonblank reason for this adjustment."
}
],
"action": "Provide the actual adjustment date and reason. This change records rebate and discounted status. Submit the corrected payload with a new idempotency key.",
"retryable": false,
"error_id": "aaaaaaaa-aaaa-4aaa-aaaa-aaaaaaaaaaaa",
"event_id": 123
}This recorded rejection leaves the business rows unchanged. Supply the actual adjustment metadata and a new idempotency key for the corrected attempt. The original key continues to replay the rejection. A valid margin reduction is a business change that creates a rebate and discounted status; see disbursement rules.
Choose a safe recovery
| Situation | Next step |
|---|---|
| Timeout, connection loss, empty/non-JSON response, or uncertain commit | Keep the original key and exact payload. Check or retry that request. A missing response does not prove that the write failed. |
retryable: true | Retry after a short delay. An ingest retry uses the same key and identical payload. |
| Validation rejected before reserving the key | Correct the request. The unreserved key can be reused; follow the returned action. |
| Recorded business rejection | Resolve the issue and submit a new attempt with a new key. This also applies when only related resource state changes and the payload stays the same. |
IDEMPOTENCY_KEY_REUSED | Restore the original payload for a retry, or choose a new key for a genuinely new operation. |
SCHEMA_NOT_READY or CONTENT_HASH_NOT_INITIALIZED | Contact support for tenant setup or hash backfill. Do not reset business data. |
Do not derive retry behavior from HTTP status alone. A 500 or 503 can need operator action, and validation is not universally returned as 422. Use retryable and action where available. Read idempotency for request identity and durable replay.
Handle batch results and historical replays
A committed batch returns HTTP 200. Inspect every results[].status and results[].body. The wrapper also carries the current zero-based index and submitted idempotency_key, including for errors and replayed results. The wrapper identifies the submitted item without modifying its stored response body. See the mixed-result example.
Successful neighbors commit when the batch transaction commits. Authentication, envelope, readiness, and whole-transaction failures instead fail the request. A failed or ambiguous commit does not confirm any item's outcome; preserve the keys and payloads of all uncertain items.
Stored statuses and bodies are immutable. Historical snapshots, reconstructed legacy responses, and older in-progress records can lack code, issues, action, retryable, or error_id. Fall back to the HTTP/item status and string error; do not assume that upgrading the API enriches stored responses. Legacy records may report IDEMPOTENCY_REQUEST_IN_PROGRESS in error or reconstruct an older PROCESSING_ERROR.
Public error codes
These response codes are relevant to the ingestion, table-read, synchronization, and health routes in this documentation. The API reference describes each route's response schemas. Unknown codes should still be surfaced with their status and recovery instructions.
| Codes | HTTP | Meaning / next step |
|---|---|---|
INVALID_JSON, INVALID_BODY, INVALID_JSON_VALUE | 400 | Correct JSON syntax, body shape, or unsupported JSON values. |
UNKNOWN_FIELD, VALIDATION_FAILED, PAYLOAD_VALIDATION_FAILED | 400 | Follow issue paths to correct supported fields, types, bounds, or nullability. |
INVALID_IDEMPOTENCY_KEY | 400 | Supply a nonblank key of at most 255 UTF-8 bytes. |
INVALID_BATCH, BATCH_TOO_LARGE, MIXED_BATCH_CATEGORIES | 400 | Send 1-100 valid items of one category. |
DISBURSEMENT_CHANGE_METADATA_REQUIRED | 400 | Supply the actual date and reason for the identified adjustment. |
DISBURSEMENT_VALIDATION_FAILED, PAYMENT_VALIDATION_ERROR, MONEY_VALIDATION_ERROR | 400 | Correct merged business values, linkage, or monetary bounds. |
ENTITY_NOT_FOUND, PURCHASE_PAYMENT_CLIENT_MISMATCH | 400 | Check the referenced resource or link the payment client to its purchase. |
INVALID_QUERY, INVALID_CURSOR | 400 | Correct the query parameter or use a cursor returned by the same endpoint. |
INVALID_ID, INVALID_TABLE | 400 | Correct the identifier or select a supported table. |
UNAUTHORIZED | 401 | Send a valid bearer API-key secret. Unknown, invalid, and disabled secrets are indistinguishable. |
FORBIDDEN | 403 | Check optional internal-secret headers; public callers need bearer authentication only. |
ROUTE_NOT_FOUND, RECORD_NOT_FOUND, UPDATE_TARGET_NOT_FOUND, TABLE_NOT_FOUND | 404 | Check the route, record ID, environment, or table provisioning. |
METHOD_NOT_ALLOWED | 405 | Use a method listed in the Allow response header. |
IDEMPOTENCY_KEY_REUSED, DUPLICATE_CREATE | 409 | Resolve request identity or use an update for an existing business record. |
CLIENT_DELETE_RESTRICTED, DISBURSEMENT_DELETE_RESTRICTED | 409 | Resolve active dependencies before deleting. |
CONTENT_HASH_NOT_INITIALIZED | 409 | Ask the operator to complete the v3 hash backfill; refresh cached sync state afterward. |
REQUEST_TOO_LARGE | 413 | Reduce the ingest body to at most 1 MiB. |
SCHEMA_NOT_READY | 503 | An operator must complete the tenant schema migration. |
AUTH_METADATA_INVALID, AUTH_STORAGE_UNAVAILABLE | 503 | Operator-side authentication metadata or storage needs attention. |
SERVICE_UNAVAILABLE | 503 | Recognized transient dependency failure; follow retryable and action. |
INTERNAL_ERROR, TENANT_CONFIGURATION_ERROR | 500 | Contact support with the failure and request identifiers. |
Trace a request
Every Worker response carries X-Correlation-ID, including successes and replays. You may send a value containing 1-128 letters, digits, ., _, :, or -; unsupported values are replaced with a generated ID. Retain the response header because it contains the ID actually used.
X-Correlation-ID identifies the current HTTP request. error_id identifies the failure, and a recorded ingestion failure replays its original error_id. Send both values, the actual HTTP/item status, and the relevant event ID to support. Neither identifier replaces the idempotency key.
A provider-generated failure can lack a Worker error body or correlation header. Preserve the actual status, available headers, and whether the outcome is unknown. Do not invent an API code or create a new ingest key merely because the response was empty or could not be parsed.
