Guides

Copy page

Error Handling

HTTP error responses follow a consistent envelope:

Code
 
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Every response also includes a server-assigned x-request-id header containing a UUIDv4. For errors, the header value and error.request_id are identical. Include this request ID when contacting support.

Error Codes

HTTP Status	Code	Description
400	VALIDATION_ERROR	Invalid request body or query parameters, including unparseable JSON — correct the request before retrying
401	UNAUTHORIZED	Missing or invalid API key
403	FORBIDDEN	Valid key but insufficient permissions
404	NOT_FOUND	Resource does not exist or is not accessible
409	TRANSACTION_CONFLICT	Write conflict — retry the request
413	PAYLOAD_TOO_LARGE	Request body exceeds 1 MiB — reduce the payload before retrying
429	RATE_LIMITED	Rate limit exceeded — wait for the reset window and retry
500	INTERNAL_ERROR	Unexpected server error
503	TRANSACTION_TIMEOUT	Database transaction timed out — retry the request
502	INTERNAL_ERROR	Gateway could not connect to an upstream service
503	SERVICE_UNAVAILABLE	Rate-limit service unavailable or backend not ready
504	SERVICE_UNAVAILABLE	Upstream operation exceeded its deadline
415	UNSUPPORTED_MEDIA_TYPE	Unsupported content type or content encoding

Handling Errors in Code

Code
 
const response = await fetch('/v1/items', {
  headers: { 'Authorization': `Bearer ${key}` },
});

if (!response.ok) {
  const { error } = await response.json();
  console.error(`[${error.code}] ${error.message} (request: ${error.request_id})`);
  // Do not retry 400 or 413 without correcting the request.
  // Retry transient failures with backoff. For an ambiguous order POST,
  // reuse the same Idempotency-Key and identical body to avoid duplicates.
}

For POST /v1/sales-orders, send an Idempotency-Key (1–255 characters), scoped to your tenant.

• Replay an ambiguous request: If the POST response is lost or a timeout leaves acceptance uncertain, replay the identical body with the same key. This does not retry failed processing. Once accepted, poll data._links.self.
• Submit a corrected order: A corrected creation submission requires a new key. Changing the payload while reusing the original key returns 409. A new key permits a new submission; consumer duplicate handling must make that submission safe.
• Attachment or ambiguous processing failures: Do not automatically resubmit ORDER_ATTACHMENT_FAILED or ORDER_PROCESSING_FAILED, including with a new key. Direct users to support because an order may already exist.

Do not assume other write endpoints are idempotent or automatically retry account/key creation.

Gateway request bodies are limited to 1 MiB before parsing or signing, including chunked requests. Use uncompressed JSON for writes. Gateway backend forwarding has a 45-second deadline. A 502/504 does not establish whether an upstream write committed.

Sales-order processing failures

Poll the URL returned in data._links.self after creation. 202 Accepted means the submission is queued, not that the order was successfully created. A queued submission is available through GET with its queue-derived status. GET returns 200 OK whenever the record is found, including pending or failed processing. 404 means not found or inaccessible; it does not mean “still processing.”

Always inspect data.queue_error, even when data.status is a normal order status such as confirmed. Canonical order statuses remain unchanged. queue_error is omitted when the queue is not failed; its absence alone does not establish successful creation.

Display queue_error.message and any optional queue_error.skus. Unknown or unresolved item IDs are never returned. Known validation messages cover inactive items, phone number length, attention length, and attachment filename length. Other errors use safe generic wording.

Public code	Meaning
ORDER_CREATE_FAILED	Order creation failed
ORDER_ATTACHMENT_FAILED	Attachment processing failed; the order may already exist
ORDER_PROCESSING_FAILED	Unrecognized processing failure; contact support

Compatibility change: queue_result_code now contains one of these public failure codes, duplicate, or null, rather than raw worker codes.

Example failed-processing fields, returned alongside existing order details with HTTP 200:

Code
 
{
  "data": {
    "id": "990e8400-e29b-41d4-a716-446655440000",
    "status": "failed_erp",
    "order_status": "failed",
    "queue_result_code": "ORDER_CREATE_FAILED",
    "queue_error": {
      "code": "ORDER_CREATE_FAILED",
      "message": "Inactive items cannot be added to an order.",
      "skus": ["ABC-123"]
    }
  }
}

Do not automatically resubmit attachment failures or ambiguous processing failures. Direct users to support; an order may already exist.