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 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.