Error codes
All API errors return a JSON body with a machine-readable error code, a human-readable message, optional details (for example, which field failed validation) and a request_id to quote when you contact support.
{ "error": "validation_error", "message": "The request contains invalid or missing fields.", "details": {"prompt": "required"}, "request_id": "req_a1b2c3d4e5f60708"}Error reference
Section titled “Error reference”| HTTP | Code | Meaning | What to do |
|---|---|---|---|
| 400 | model_not_available |
The requested model is not available | Pick a model from GET /v1/models |
| 401 | auth_missing_api_key |
No API key provided | Send Authorization: Bearer dpct_... |
| 401 | auth_invalid_api_key |
API key is invalid or has been revoked | Check the key is copied correctly; if it was revoked, create a new key in the dashboard |
| 401 | auth_revoked_api_key |
API key has been revoked | Create a new key in the dashboard |
| 402 | credit_insufficient_balance |
Not enough credits for this request | Top up credits in the dashboard |
| 402 | credit_expired |
Your credits have expired | Top up to restore your balance |
| 402 | model_restricted |
Low balance: only budget models are available | Top up, or use a budget model |
| 403 | auth_account_suspended |
Account suspended. API keys stop working; signed in to the dashboard you can still see billing, withdraw from a purchase, export your data or close the account | Contact support |
| 403 | auth_email_not_verified |
Email not verified | Check your inbox for the verification link |
| 403 | generation_paused |
Image generation is paused on your account while we review recent requests. Your account, credits and payments are not affected | Wait for the review; we usually finish within one business day. You can also write to hello@depicta.ai |
| 403 | auth_session_required |
This action needs you signed in to the dashboard; API keys aren’t accepted. Managing the account (API keys, billing, withdrawals, settings, data export, closure) happens there | Do it in the dashboard |
| 403 | model_not_allowed |
Model is outside your allowed_models preference |
Choose an allowed model or change your preferences |
| 404 | not_found |
Endpoint or resource not found | Check the URL and method |
| 422 | input_image_unreachable |
An input or reference image URL could not be downloaded; details names the field and the reason (blocked_address, http_status, timeout, too_large, not_an_image or connection_failed). A story’s references are named by position (for example characters[0].reference_url). No credits are charged |
Fix the URL, or upload the image with POST /v1/upload; retrying unchanged fails again |
| 422 | model_not_capable |
The model does not support this operation (for example, story on a model other than gemini or gemini-pro) |
Choose a model that supports the operation |
| 422 | validation_error |
Invalid or missing fields; details names each field and the problem. Also used for uploads over 50 MB, more input images than the model accepts, an aspect_ratio or image_size the model doesn’t list in GET /v1/models, and story options that aren’t supported yet. Nothing is charged |
Fix the fields listed in details |
| 429 | rate_limit_exceeded |
Too many concurrent requests, or 3 stories already in progress | Wait for the Retry-After header duration |
| 451 | content_rejected |
Prompt or image violates the content policy | Revise your prompt and try again |
| 451 | model_content_rejected |
The image model returned no image (often its provider declining, not always because of your content). No credits are charged | Try again, rephrase, or choose another model |
| 451 | output_withheld |
The generated image was withheld because it may break our content rules. You have not been charged. In a story, a withheld image means the story is not delivered | Change your request and try again |
| 500 | internal_error |
Unexpected server error | Retry with backoff; check the status page |
| 502 | upstream_error |
The image model rejected the request | Adjust your inputs or switch model; retrying as-is will fail |
| 503 | classifier_unavailable |
Content moderation is temporarily unavailable | Retry shortly |
| 503 | service_unavailable |
Temporary outage, or the chosen model is temporarily unavailable | Retry with backoff or switch model |
The API reference documents each endpoint; the error codes it can return are the ones on this page.
A story that fails has status: failed and an error object (code, message) in GET /v1/jobs/{id}. For example, service_unavailable means the story couldn’t start within 30 minutes; nothing is charged.
CLI exit codes
Section titled “CLI exit codes”The CLI maps API errors to exit codes:
| Exit code | Meaning | Corresponding API errors |
|---|---|---|
| 0 | Success | — |
| 1 | General error | Any error not listed below, including every 403 (model_not_allowed, auth_account_suspended, auth_email_not_verified, auth_session_required, generation_paused) and 422 (validation_error, model_not_capable) |
| 2 | Authentication failure | 401 (auth_missing_api_key, auth_invalid_api_key, auth_revoked_api_key) |
| 3 | Insufficient credits | 402 (credit_insufficient_balance, credit_expired, model_restricted) |
| 4 | Content rejected | 451 (content_rejected, model_content_rejected, output_withheld) |
| 5 | Rate limited | 429 (rate_limit_exceeded) |
The CLI first retries a 429 itself: up to 3 attempts, waiting as long as the Retry-After header says, for up to about 30 seconds in all. Exit 5 means those retries ran out; the JSON error then carries retry_after, the seconds to wait.
The CLI maps errors by HTTP status, so a code added to the API later lands in the right group. These exit codes are from CLI 1.4.0; earlier versions mapped some errors differently, so update with npm install -g depicta or pip install --upgrade depicta.