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