Error codes

Every API error arrives in the same envelope:

{
  "error": {
    "code": "insufficient_funds",
    "message": "not enough doubloons: need 150, balance is 100"
  }
}

code is a machine string — branch on it in your code. message is for humans; its format is not guaranteed, don't parse it.

Code table

HTTP	code	Meaning	What to do
400	bad_request	Malformed request overall	Check body and headers
401	unauthorized	Key missing, invalid, or revoked	Reissue the key: /apikey in the bot
402	insufficient_funds	Not enough doubloons for the order	Top up in the bot; check GET /balance
403	forbidden	Access denied	Make sure your key touches your own resources
404	not_found	No such order, webhook, or file	Check the id; order files live 30 days
409	fair_use_exceeded	Plan fair-use limit exhausted (heavy videos)	Wait for next month or pay in doubloons
409	not_awaiting_review	The order is not waiting for script review	Review only works in awaiting_review
422	invalid_params	Body failed validation	message names the field and the reason
429	rate_limited	Over 30 POST/minute on the key	Slow down, respect Retry-After
429	active_tasks_exceeded	Already 10 active tasks (queued+running)	Wait for done/error, respect Retry-After
500	internal_error	Something broke on our side	Retry with backoff; if it persists — support
502	generator_unavailable	Generator temporarily unavailable	Retry with backoff
503	service_unavailable	Service under maintenance	Retry with backoff

Limits and Retry-After

Each key has two limits: 10 active tasks (queued + running) and 30 POST per minute. Exceeding either returns 429 with a Retry-After header (seconds until the next attempt). Respect it — it's cheaper than guessing.

Good manners

• Idempotency-Key on every POST to /videos and /videos:quick — client retries must not double-charge. A repeat with the same key within 24 hours returns the original task (200 instead of 201).
• Retry GETs with exponential backoff and jitter; on 429/5xx follow Retry-After.
• A generation failure (status: "error" on the order) is not an HTTP error: doubloons for it are refunded to the balance automatically, same as in the bot.

Support: @piratepress_support.