Error handling

The API uses standard GraphQL error responses. Errors are returned in the errors array alongside any partial data.

Error response shape

{
  "data": null,
  "errors": [
    {
      "message": "authentication required for this mutation",
      "path": ["createSecondaryMarketOrder"],
      "extensions": {
        "Code": "IAM_UNAUTHENTICATED",
        "Expected": true
      }
    }
  ]
}

Common error codes

Permission errors

When a permission check fails, the error extensions include additional context:

{
  "message": "permission denied",
  "extensions": {
    "Code": "IAM_FORBIDDEN",
    "Expected": true,
    "PermissionName": "account.read",
    "PermissionScope": "ACCOUNT"
  }
}

Handling errors in your integration

1. Always check the errors array, even when HTTP status is 200.
2. Use extensions.Code for programmatic error handling — do not parse message strings.
3. Retry only on transient errors (UNEXPECTED_ERROR). Do not retry authentication or permission errors without fixing the underlying issue.
4. Use idempotency keys when retrying mutations to avoid duplicate side effects.

Partial errors

GraphQL can return partial data when some fields fail and others succeed. Check both data and errors in every response.

{
  "data": {
    "account": { "id": "account|abc", "status": "ACTIVE" },
    "linkedUsers": null
  },
  "errors": [
    {
      "message": "permission denied",
      "path": ["account", "linkedUsers"],
      "extensions": { "Code": "IAM_FORBIDDEN", "Expected": true }
    }
  ]
}

HTTP status codes