---
title: "GPT-Video API errors and what to do next"
description: "Every error code the GPT-Video API can answer, with its HTTP status, what it means and what your code or agent should do next."
url: "https://www.gpt-video.com/developers/errors"
---

# Errors

When a call fails, the API answers with an error body and an HTTP status. Decide what to do from the `code` inside the body. The status alone is not enough. A 429 can mean wait a minute, and it can also mean stop until tomorrow.

## The error body

Every error has the same shape, an object named `error` with these fields.

- `code` is the name of the error. The list below gives every code.
- `message` says what went wrong, in one sentence for a person.
- `hint` says what to do next, written for a program or an AI agent. It is not always present.
- `requestId` is the id of the request. Give it to us if you ask for help with a call.
- `details` holds extra facts for some codes. It is not always present.

The `X-Request-Id` header carries the same id as `requestId`.

## What to do

Each code has one action. Read the action first, then the sentence for the code.

- **Fix the request.** The call cannot work as sent. Change the request, then send a new one.
- **Ask the user.** A person has to act, for example by adding credits or choosing a plan. Stop and tell them.
- **Wait, then retry.** Wait for the time in the `Retry-After` header, then send the same request.
- **Retry the same request.** Send the same request again with the same `Idempotency-Key`, at most three times.
- **Read, then decide.** Read the resource again to see its state. Do not send the same request again.
- **Stop until the limit resets.** A daily limit is used up. It resets at 00:00 UTC. Tell the user.

Sending the same request again with the same `Idempotency-Key` never spends credits twice. [Pagination and idempotency](/developers/pagination-and-idempotency.md) explains how the key works.

## An operation that is switched off

A `503` with the code `UNAVAILABLE` has two causes. The service can be busy, and then waiting for `Retry-After` is right. An operation can also be switched off for now. In that case `details.reason` is `switched_off`, and you should not retry. Tell the user that the operation is not available yet.

## Errors on every call

Every operation can answer `VALIDATION_FAILED`, `UNKNOWN_PARAMETER`, `UNAUTHORIZED`, `SCOPE_MISSING`, `RATE_LIMITED`, `INTERNAL` and `UNAVAILABLE`. A call that sends a body can also answer `PAYLOAD_TOO_LARGE`. A call that spends credits or creates something also uses the `Idempotency-Key`, so it can answer the errors of that header too. The page of each operation lists only the errors that are particular to it, and links here for the rest.

## All error codes

Each code below has its HTTP status, what it means and what to do. The links on the pages of the operations point to these entries.

## Error codes

Each row is one value of `error.code`. Decide what to do from the code. The HTTP status is only its class.

| Code | Status | Meaning | Action | What to do |
| --- | --- | --- | --- | --- |
| `VALIDATION_FAILED` | 400 | The request does not match what the operation accepts. | Fix the request | Fix the fields listed in details.issues, then send the request again. Fix the request as the message says, then send it again. |
| `UNKNOWN_PARAMETER` | 400 | The request has a field or a parameter that the operation does not take. | Fix the request | Send only the fields listed in details.allowed. |
| `IDEMPOTENCY_KEY_REQUIRED` | 400 | The operation spends, and the request has no Idempotency-Key header. | Fix the request | Add an Idempotency-Key header: a random string such as a UUID, the same one on every retry of this request. |
| `UNAUTHORIZED` | 401 | The API key is missing, wrong or revoked, or the account cannot use the API yet. | Ask the user | Send an API key in the Authorization header as Bearer gvk_... You create keys in the GPT-Video app. |
| `INSUFFICIENT_CREDITS` | 402 | The account does not have enough credits for this call. | Ask the user | Buy credits or change plan at https://www.gpt-video.com/app/billing. |
| `PLAN_REQUIRED` | 402 | The account has no Creator or Studio plan, and neither the API bonus nor the allowance of the account can pay for this call. | Ask the user | The API bonus pays first. When it cannot, choose a Creator or Studio plan at https://www.gpt-video.com/app/billing. |
| `SCOPE_MISSING` | 403 | The API key does not have a scope that this operation needs. | Ask the user | Create a key with the scope named in the message, or use a key that has it. |
| `NOT_FOUND` | 404 | The resource does not exist, or it belongs to another account. | Fix the request | Check the id. An id that belongs to another account is not found either. |
| `METHOD_NOT_ALLOWED` | 405 | The path exists, but it does not take this HTTP method. | Fix the request | Use one of the methods listed in the Allow header. |
| `CONFLICT` | 409 | The current state of the resource does not allow this call. | Read, then decide | Read the resource again, then decide. Do not send the same request again. |
| `NOT_READY` | 409 | The resource is still being made or changed, so the call cannot run yet. | Wait, then retry | Wait the number of seconds in the Retry-After header, then send the same request again. |
| `IDEMPOTENCY_IN_PROGRESS` | 409 | A request with the same Idempotency-Key is still running. | Wait, then retry | Wait the number of seconds in the Retry-After header, then send the same request again to get its result. |
| `PAYLOAD_TOO_LARGE` | 413 | The body is larger than the operation accepts. | Fix the request | Send a JSON body of at most 1 MB. |
| `IDEMPOTENCY_KEY_REUSED` | 422 | The Idempotency-Key was already used for a different request. | Fix the request | Use a new Idempotency-Key for a different request. |
| `SOURCE_MISSING` | 422 | The source video that the call needs is missing or no longer exists. | Fix the request | A project's video cannot be changed through the API. Upload the video, then create a new project with its asset id as sourceAssetId. |
| `UNSUPPORTED_SOURCE_URL` | 422 | The link does not point to a video file that GPT-Video can download. | Fix the request | Send a direct link to a video file. A link to a web page is refused. |
| `RATE_LIMITED` | 429 | The key or the account sent too many requests of this kind in the current minute. | Wait, then retry | Wait the number of seconds in the Retry-After header, then send the request again. |
| `DAILY_LIMIT_REACHED` | 429 | A daily limit of the account or of the API bonus is used up until 00:00 UTC. | Stop until reset | The limit resets at 00:00 UTC. A higher plan raises it: https://www.gpt-video.com/app/billing. |
| `INTERNAL` | 500 | Something failed on the side of GPT-Video. | Retry the same request | Retry the same request, with the same Idempotency-Key if it has one. If it keeps failing, contact support and quote the requestId. |
| `UPSTREAM_FAILED` | 502 | A service that GPT-Video depends on failed. | Retry the same request | Retry in a few minutes. |
| `UNAVAILABLE` | 503 | GPT-Video cannot take this work right now, or this operation is turned off. | Wait, then retry | Retry later. |

## When to send a request again

Send the same request again, with the same `Idempotency-Key`, only after one of these codes.

- `NOT_READY` (409)
- `IDEMPOTENCY_IN_PROGRESS` (409)
- `RATE_LIMITED` (429)
- `INTERNAL` (500)
- `UPSTREAM_FAILED` (502)
- `UNAVAILABLE` (503)

When the answer has a `Retry-After` header, wait that many seconds first. Try `UNAVAILABLE`, `INTERNAL` and `UPSTREAM_FAILED` at most three times.

## An operation that is turned off

A `503` `UNAVAILABLE` answer with `details.reason: "switched_off"` means this. This operation is turned off for now, so sending it again does not help. The other operations work as usual.

## Why the API bonus did not pay

A `PLAN_REQUIRED` or `DAILY_LIMIT_REACHED` answer about the API bonus has `details.bonus`. Its value says why the bonus could not pay.

| details.bonus | What to do |
| --- | --- |
| `paused` | The API bonus is paused right now, so only a Creator or Studio plan can pay for this. Choose one at https://www.gpt-video.com/app/billing. |
| `spend_cap` | Choose a Creator or Studio plan to keep going now: https://www.gpt-video.com/app/billing. |
| `short` | The API bonus pays only for a whole action. Choose a Creator or Studio plan at https://www.gpt-video.com/app/billing. |
| `used_up` | Your API bonus is used up or expired. Choose a Creator or Studio plan at https://www.gpt-video.com/app/billing. |
| `expired` | Your API bonus is used up or expired. Choose a Creator or Studio plan at https://www.gpt-video.com/app/billing. |
| `cancelled` | Your API bonus was cancelled. Choose a Creator or Studio plan at https://www.gpt-video.com/app/billing. |
| `rail` | Choose a Creator or Studio plan for a higher limit: https://www.gpt-video.com/app/billing. |