Errors

Errors are returned as JSON with an error code and, where useful, a message or a fields map. Always branch on the HTTP status code first.

Status	error	Meaning	How to fix
400	bad_request	The body was not valid JSON.	Send well-formed JSON with Content-Type: application/json.
401	unauthorized	Missing or invalid API key.	Send a valid key (see Authentication); create a new one if revoked.
422	validation_failed	One or more fields are invalid.	Inspect fields and correct each entry.
500	internal_error	Unexpected server error.	Retry with backoff; if it persists, contact support.

Validation errors (422)

The fields object maps each invalid field to a reason:

{
  "error": "validation_failed",
  "fields": {
    "side": "must be one of: open, close",
    "source": "is required"
  }
}

Recommended client handling

• 2xx — success. On 200 check deduped to know it was a retry.
• 400 / 422 — do not retry unchanged; the request is malformed or invalid.
• 401 — fix credentials before retrying.
• 429 / 5xx — retry with exponential backoff and jitter. Pair retries with a client_signal_id so they stay idempotent.