Every error code the GhostShorts API returns
Back to the GhostShorts API reference.
Errors are RFC 9457 problem JSON (application/problem+json): { type, title, status, detail, code }, plus an errors array on INVALID_INPUT and upsell + plansUrl on every 402. Branch on code.
| Code | HTTP | What it means |
|---|---|---|
MISSING_API_KEY | 401 | No Authorization: Bearer header was sent. |
INVALID_API_KEY | 401 | The key is unknown or has been revoked. Create a new one in Settings. |
UNSUPPORTED_TOKEN | 401 | The bearer token is not a GhostShorts API key (gs_live_...). |
UNAUTHENTICATED | 401 | The request reached an endpoint without an authenticated account. Send your API key. |
SUBSCRIPTION_REQUIRED | 402 | This step needs an active plan. The response carries plansUrl. |
INSUFFICIENT_CREDITS | 402 | Not enough credits for this step. Top up or wait for your plan to renew. |
INSUFFICIENT_AI_CREDITS | 402 | Not enough AI credits for this step. |
VIDEO_ALLOWANCE_EXHAUSTED | 402 | This month's video allowance is used up. |
CLIPPING_ALLOWANCE_EXHAUSTED | 402 | This month's clipping minutes are used up. |
SOFT_CAP_REACHED | 402 | A fair-use limit for this period was reached. |
INVALID_INPUT | 400 | The body does not match the schema. The errors array names each field. Also sent as 413 for a body over 2 MB. |
INVALID_VOICE | 400 | That voice id is not available for this template. See GET /v1/options voices. |
UNKNOWN_TEMPLATE | 400 | No template with that id. See GET /v1/templates. |
TEMPLATE_NOT_AVAILABLE | 400 | The template has no such step through the API (for example POST /v1/scripts for reddit_story). The detail says what to call instead. |
NARRATION_REQUIRED | 400 | The video cannot be rendered without narration. |
INVALID_WEBHOOK_URL | 400 | webhookUrl must be a public https URL. |
SAFETY_REJECTED | 400 | The content was refused by our safety checks. Change the topic or text. |
INVALID_IDEMPOTENCY_KEY | 400 | The Idempotency-Key header is empty or longer than 255 characters. |
NOT_FOUND | 404 | No such endpoint, or no such video, project or download link on this account. |
IDEMPOTENCY_IN_PROGRESS | 409 | A request with this Idempotency-Key is still running. Retry after Retry-After. |
CANNOT_CANCEL | 409 | Only a queued video can be cancelled. |
LINK_EXPIRED | 410 | The download link is past its 7 days. GET /v1/videos/{id} again for a fresh one. |
IDEMPOTENCY_KEY_REUSED | 422 | This Idempotency-Key was already used with a different body. Use a new key for a new request. |
RATE_LIMITED | 429 | Too many requests. Wait for Retry-After seconds. |
CONCURRENCY_LIMIT | 429 | Three videos are already in progress on this account. Retry after one finishes. |
INTERNAL_ERROR | 500 | Something failed on our side. Retry; the same Idempotency-Key is safe to reuse. |
RATE_LIMITER_UNAVAILABLE | 503 | Rate limiting is briefly unavailable, so the request was refused. Retry shortly. |
SERVICE_UNAVAILABLE | 503 | The video queue is briefly unavailable. Nothing was charged; retry shortly. |
When a video ends as failed or cancelled, error.code on the video (and in the video.failed webhook) is one of these. error.message always says what happened.
| Code | What it means |
|---|---|
MEDIA_FETCH_FAILED | Your background or music URL could not be downloaded: not public https, not reachable, refused, or larger than 300 MB (video) / 30 MB (audio). |
MEDIA_INVALID | The file at your URL is not a usable video or audio file. |
MEDIA_TOO_LONG | The file at your URL is longer than 10 minutes. |
MEDIA_QUOTA_EXCEEDED | More than 20 new media URLs today. Reuse a URL (free for 30 days) or wait. |
BACKGROUND_UNAVAILABLE | The background video or category you picked has no usable footage. Pick one from GET /v1/options. |
MUSIC_UNAVAILABLE | The music id is not in the library. Pick one from GET /v1/options music. |
IMAGE_UNAVAILABLE | An avatar or photo id is not an image you can use. |
SCRIPT_FAILED | The script could not be written. |
PACK_FAILED | The quiz questions could not be written. |
INGEST_FAILED | The article at your URL could not be read. Paste the text instead. |
SOURCE_TOO_SHORT | The article is too short to make a script from. |
NARRATION_FAILED | The narration could not be recorded. |
VOICE_TTS_FAILED | The voice provider failed while recording. |
RENDER_FAILED | The render failed. Create the video again. |
INTERRUPTED | Processing was interrupted. Create the video again; contact support if narration was charged. |
CANCELLED | You cancelled the video while it was queued. |
