Errors & refunds

Status codes

Error shape

All errors return JSON with an error field. Some include additional keys.

{
  "error": "Invalid request",
  "details": {
    "formErrors": [],
    "fieldErrors": {
      "prompt": ["Prompt is required"]
    }
  }
}

{
  "error": "Insufficient credits",
  "required": 12
}

{ "error": "Unauthorized" }

Automatic refunds

Credits are pre-debited at submission time. If the task ends in status: 2 (FAILED) — for any reason, including provider timeouts and storage errors — credits are refunded atomically via a creditRefunded flag on the task row. You do not need to request the refund.

The refunded amount equals creditsUsed from the submission response. Check creditsRefunded: true in the GET /api/ai/tasks/{id} response to confirm.

Common failure modes

• EMPTY_RESULT — the upstream provider reported success but returned no output URL. Auto-refund applies.
• STORAGE_ERROR — we could not persist the upstream output to our CDN. Auto-refund applies.
• Provider-specific codes — passed through from the upstream model. Auto-refund applies.

Idempotency

Endpoints are not yet idempotent. If a POST /generate call times out from the client side, check for any recent tasks belonging to your account via the dashboard before retrying, to avoid double-charging.