Errors

Error response shape, status codes, retry behavior, and logging guidance.

Errors use a JSON envelope with a stable upper-case code and human-readable message.

{
  "status": "error",
  "error": {
    "code": "UNAUTHORIZED",
    "message": "missing X-Api-Key header"
  }
}

Do not parse message for control flow. Use HTTP status and error.code for programmatic handling.

Common Status Codes

Status	Meaning	Action
400	Invalid request	Fix parameters, filters, enum values, or body fields
401	Missing or invalid API key	Check X-Api-Key
403	Access or account requirement not met	Confirm key access and account readiness
404	Resource not found	Verify the public identifier and account context
409	Conflict	Check idempotency, duplicate intent, or current resource state
429	Too many requests	Back off and retry later

Retry Guidance

Class	Retry?	Notes
400	No	The request is malformed or semantically invalid
401	No	Fix credentials or environment
403	No	Fix key access or account readiness
404	Usually no	Retry only if you expect eventual visibility after a recent action
409	Depends	For idempotency conflicts, read the existing order or create a new intent
429	Yes, after backoff	Slow down the caller and keep idempotency keys stable for order writes
5xx	Yes, bounded	Retry with backoff; for order writes reuse the same Idempotency-Key

Required Headers

Use X-Api-Key on authenticated endpoints. Use Content-Type: application/json on JSON writes. Use Idempotency-Key on order create, cancel, and replace requests.