Errors and Limits

Failure classes

• Bad or missing key - the request is unauthenticated. Check that the Authorization: Bearer sk-... header is set and the key still exists (deleted keys keep failing until you switch keys).
• Insufficient balance - the account balance cannot cover the request. The check happens before generation starts - a request the balance cannot cover is rejected up front, never interrupted midway. Top up via Funds.
• Rate limited - too many requests in the sliding window. Back off and retry; see the rate limits pattern.
• Unsupported parameter for the model (HTTP 400) - e.g. a video resolution the model does not serve. The error names what is wrong; the public pricing catalog lists per-model video_resolutions.
• Upstream failure - the channel errored. The gateway does not bill requests that fail before generation. Retrying is usually correct; for a structured approach see the error recovery pattern.

Retries

Retry with backoff on rate limits and upstream failures. Do NOT retry a 401 or an insufficient-balance rejection - they will fail identically until you act (fix the key / top up). Idempotent reads (models, pricing, poll endpoints) are always safe to retry.

Billing and failures

You are billed only for tokens actually processed - requests that fail before generation are not billed. Video tasks reserve funds while running and refund in full when cancelled while queued - see cancel semantics.

Where errors appear

Every request your key makes is visible in the console Logs with its outcome - useful when a client library swallows the response body.