Developers
Show batch ingestion and synchronization guides and endpoints, core concepts, and the content hash calculator.
Explore the docs

Get started

Errors and recovery

Read API error codes and field issues, diagnose failed items, and retry without duplicating work.

On this page

At a glance#

  • Use code for error handling and issues for field-level feedback.
  • Keep error_id and the current X-Correlation-ID when contacting support.
  • Preserve the original key and payload whenever an ingestion outcome is uncertain.

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

FieldHow to use it
codeStable failure reason for programmatic handling. Tolerate unknown codes.
errorHuman-readable summary; do not parse this text for control flow.
message, detailsLegacy explanation when present. details can be a string or an array of strings.
issuesUp to 50 problems with location, path, code, message, and optional expected constraints.
contextRelevant resource or business facts. Monetary adjustment values use normalized decimal strings.
actionRecovery instructions. On an error this is guidance text; success responses use actions such as created or unchanged.
retryableWhether automatically repeating this operation is appropriate. false does not mean the service can never recover.
error_idFailure identifier. A recorded rejection keeps this same value on replay.
event_idPresent 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:

json
{
  "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

SituationNext step
Timeout, connection loss, empty/non-JSON response, or uncertain commitKeep the original key and exact payload. Check or retry that request. A missing response does not prove that the write failed.
retryable: trueRetry after a short delay. An ingest retry uses the same key and identical payload.
Validation rejected before reserving the keyCorrect the request. The unreserved key can be reused; follow the returned action.
Recorded business rejectionResolve 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_REUSEDRestore the original payload for a retry, or choose a new key for a genuinely new operation.
SCHEMA_NOT_READY or CONTENT_HASH_NOT_INITIALIZEDContact 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.

CodesHTTPMeaning / next step
INVALID_JSON, INVALID_BODY, INVALID_JSON_VALUE400Correct JSON syntax, body shape, or unsupported JSON values.
UNKNOWN_FIELD, VALIDATION_FAILED, PAYLOAD_VALIDATION_FAILED400Follow issue paths to correct supported fields, types, bounds, or nullability.
INVALID_IDEMPOTENCY_KEY400Supply a nonblank key of at most 255 UTF-8 bytes.
INVALID_BATCH, BATCH_TOO_LARGE, MIXED_BATCH_CATEGORIES400Send 1-100 valid items of one category.
DISBURSEMENT_CHANGE_METADATA_REQUIRED400Supply the actual date and reason for the identified adjustment.
DISBURSEMENT_VALIDATION_FAILED, PAYMENT_VALIDATION_ERROR, MONEY_VALIDATION_ERROR400Correct merged business values, linkage, or monetary bounds.
ENTITY_NOT_FOUND, PURCHASE_PAYMENT_CLIENT_MISMATCH400Check the referenced resource or link the payment client to its purchase.
INVALID_QUERY, INVALID_CURSOR400Correct the query parameter or use a cursor returned by the same endpoint.
INVALID_ID, INVALID_TABLE400Correct the identifier or select a supported table.
UNAUTHORIZED401Send a valid bearer API-key secret. Unknown, invalid, and disabled secrets are indistinguishable.
FORBIDDEN403Check optional internal-secret headers; public callers need bearer authentication only.
ROUTE_NOT_FOUND, RECORD_NOT_FOUND, UPDATE_TARGET_NOT_FOUND, TABLE_NOT_FOUND404Check the route, record ID, environment, or table provisioning.
METHOD_NOT_ALLOWED405Use a method listed in the Allow response header.
IDEMPOTENCY_KEY_REUSED, DUPLICATE_CREATE409Resolve request identity or use an update for an existing business record.
CLIENT_DELETE_RESTRICTED, DISBURSEMENT_DELETE_RESTRICTED409Resolve active dependencies before deleting.
CONTENT_HASH_NOT_INITIALIZED409Ask the operator to complete the v3 hash backfill; refresh cached sync state afterward.
REQUEST_TOO_LARGE413Reduce the ingest body to at most 1 MiB.
SCHEMA_NOT_READY503An operator must complete the tenant schema migration.
AUTH_METADATA_INVALID, AUTH_STORAGE_UNAVAILABLE503Operator-side authentication metadata or storage needs attention.
SERVICE_UNAVAILABLE503Recognized transient dependency failure; follow retryable and action.
INTERNAL_ERROR, TENANT_CONFIGURATION_ERROR500Contact 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.

Validate locally. Verify in sandbox.
The JSON validator checks structure and rounding. Credentials, existing records, and server-side state still require your test environment.

Search documentation

Start typing to find your next step.

    ↑ ↓ navigate Enter openLocal, private search