Errors

All errors share the same shape and a small, predictable set of codes.

Error format

All errors follow the same JSON shape. The HTTP status code matches the code below.

JSON

{
  "error": {
    "code": "validation_error",
    "message": "endUserEmail must be a valid email address",
    "fields": {
      "endUserEmail": "must be a valid email address"
    }
  }
}

Error codes

Code	HTTP	Description
`validation_error`	400	The request body or query parameters did not pass validation (missing required field, wrong type, value out of range). Inspect the message — it tells you what to fix.
`unauthorized`	401	Missing or invalid `Authorization` header. Check that you sent `Bearer xm_live_…` and that the key has not been revoked.
`account_blocked`	401	Your xMode account has been blocked. Existing dashboard access continues but `/v1/*` endpoints are refused. Contact support to resolve.
`forbidden`	403	The key is valid but does not have permission for this endpoint or resource.
`not_found`	404	The requested resource (request id, image id, end-user email) does not exist or does not belong to you.
`payment_required`	402	Your xTokens balance is insufficient for this request. Top up your balance in the dashboard.
`conflict`	409	Operation refused because of current state. Currently returned by `DELETE /v1/end-users/{email}` when the end-user has queued or processing generations — block first, wait for them to finish, then retry.
`content_policy`	422	The prompt or reference images were rejected by our content filter. Rephrase the prompt or use different references.
`rate_limited`	429	Too many requests in a short window. Back off and retry — check the `Retry-After` header for the suggested wait.
`provider_timeout`	500	Our upstream generation provider timed out. Safe to retry the same request. If it persists, contact support.
`provider_error`	500	Our upstream provider returned an error we could not handle. Safe to retry.
`internal_error`	500	Unexpected server error on our side. Contact support if this persists.
`storage_failed`	200	Per-image marker (returned inside `images[].error`, not as a top-level error). The model produced the image but our storage layer failed to persist it. The request as a whole is `succeeded`; only the affected image is unavailable. Safe to re-run the prompt.