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.

PreviousMCP Server