Error Handling
HTTP errors and task failures
Section titled “HTTP errors and task failures”Check the HTTP status before reading a successful response. API errors can include an error object with a message, type, or code; fields and codes vary by endpoint. Do not assume a single error envelope or an exhaustive fixed code list.
A successful polling HTTP response does not necessarily mean generation succeeded. Inspect the task’s status and, for failed, its error field. The video integration uses task_failed for a confirmed task failure; inspect the message for context.
Handling failures
Section titled “Handling failures”| Situation | Action |
|---|---|
| Authentication or access rejected | Check the API key, its status, expiry, quota, model access, and IP restrictions |
| Invalid request | Check the exact model ID, required inputs, duration, resolution, and parameter types |
| Insufficient balance or key quota | Check both account balance and the API key’s remaining quota |
| HTTP 429 | Reduce request frequency and concurrency; use bounded backoff |
| Polling connection error | Retry the GET using the same task ID |
| Submission timeout or lost response | Treat submission as uncertain; check task history or contact support before submitting again |
Task failed | Read the error, correct the cause, and decide whether a new paid submission is appropriate |
Task unknown | Stop automatic resubmission and ask support to reconcile the task |
Do not automatically repeat a paid POST just because a connection failed or an HTTP 5xx was received. The task may already have been accepted.
Diagnostics
Section titled “Diagnostics”Record the HTTP status, task ID when available, model ID, request time, and a redacted error response. Never log an API key, Authorization header, login token, or private media URL containing access credentials.
See Video Errors & Recovery and Rate Limits.