Errors and retry behavior

Non-success responses use this envelope:

{
  "error": {
    "code": "SOME_CODE",
    "message": "Human-readable explanation",
    "issues": []
  }
}

Retry guidance

Retry transport failures.
Retry idempotent writes with the same Idempotency-Key.
Re-read durable state after async work instead of assuming the first response is complete.

Treat server-side failures as retry candidates only when the original write used a stable idempotency key.
Treat fresh export download URLs as temporary and re-read them from GET /exports/{exportId} when needed.
If a mutation is already in progress or conflicts with current state, inspect the returned code and retry only when the operation is still logically safe.

The shipped Node.js SDK and CLI normalize errors into structured objects with:

That makes it safe to branch automation logic without parsing free-form strings.