Errors And OpenAPI
Handle errors and generate clients from the OpenAPI schema.
Structured Errors
Errors are returned as JSON.
{
"error": {
"code": "bad_request",
"message": "Invalid request.",
"retryable": false,
"context": {}
}
}
Common Codes
| Code | Meaning |
|---|---|
unauthorized | Missing bearer API key. |
invalid_api_key | Missing, expired, or invalid key. |
forbidden | Key is valid but missing a required scope. |
payment_required | Workspace is not on a paid plan. |
insufficient_credits | Not enough credits to queue the job. |
bad_request | Invalid body, params, or unsupported option. |
idempotency_conflict | The same idempotency key was used with a different payload. |
rate_limited | Too many requests. |
not_found | Resource does not exist or belongs to another workspace. |
server_error | Unexpected server-side failure. |
Retry Behavior
retryable is true for 429 and 5xx responses.
For rate_limited, back off before retrying.
For paid endpoints, retry with the same Idempotency-Key or idempotency_key.
Do not retry bad_request, forbidden, payment_required, insufficient_credits, or idempotency_conflict without changing the request or asking the user.
Completed Generation Failures
A failed job returned by GET /generations/{id} keeps error.code as
generation_failed. Its error.category describes the stored failure, and
error.retryable follows that failure rather than the HTTP status of the polling
request. For example, a confirmed content policy rejection is not retryable;
a temporary provider outage may be retryable.
error.credits_returned is true or false when a valid stored refund descriptor
exists, and null when the historical record does not establish the refund state.
An unknown failure is not evidence of a content policy rejection. Retrying a paid
generation remains a new paid action unless it is a retry of the same request
with its original idempotency key.
Idempotency
Use one idempotency key per paid action.
A completed matching request returns the original response.
The same key with a different payload returns 409 idempotency_conflict.
A key that is still processing also returns 409 idempotency_conflict.
GET /openapi.json
Returns the machine-readable OpenAPI schema.
curl https://videotok.app/api/v1/openapi.json
Use it for SDK generation, API clients, and agent tool creation.
GET /skill.md
Returns an agent-ready Skill.md file.
curl https://videotok.app/api/v1/skill.md
Use it when an agent needs concise Videotok API instructions.