Developers

Error reference

One error shape for every endpoint. Learn it once, handle everything.

The normalized shape

Every API failure — no matter which tool — returns JSON in this shape, with an HTTP status that matches the problem:

error shape

{
  "ok": false,
  "provider": "yatools",
  "fallbackUsed": false,
  "error": {
    "code": "MISSING_URL",
    "message": "Human-readable explanation of what went wrong."
  }
}

provider names the backend that produced the error; fallbackUsed tells you whether a fallback was already tried before failing. On success the same envelope carries a data payload instead of error — see the API quickstart.

Error codes

Code	HTTP	Meaning
`RATE_LIMITED`	`429`	Daily quota for this tool exceeded. Respect the Retry-After header and try again after the reset.
`MISSING_URL / MISSING_QUERY / MISSING_TEXT`	`400`	A required parameter is missing — url for websnap, q for search endpoints, text for tts/hand. The message names the problem.
`BAD_JSON`	`400`	A POST route received a body that isn't valid JSON.
`BAD_PROMPT`	`400`	The tti prompt is empty or longer than 500 characters. Shorten it and retry.
`BAD_RATIO / BAD_RATE / BAD_PITCH / BAD_VOICE`	`400`	An option value is outside its allowed range — e.g. an unsupported aspect ratio or an unknown voice index.
`UNSAFE_URL`	`400`	The URL failed SSRF validation (localhost, private IPs, metadata addresses). Use a public URL instead.
`URL_TOO_LONG / QUERY_TOO_LONG`	`400`	The input string exceeds the maximum allowed length.
`FILE_TOO_LARGE`	`400`	The upload exceeds the size cap (e.g. audio files must stay under 25 MB).
`TRANSCRIBE_TIMEOUT`	`502`	Transcription took too long — the audio file is likely too large. Split it into shorter parts and retry.
`MISSING_FIELDS / MISSING_IMAGE`	`400`	A POST route is missing required fields — e.g. certificate needs name, date, signature, details, templateId; vision chat needs an image and a question.
`BAD_FIELD / BAD_IMAGE`	`400`	A field failed validation — e.g. templateId outside 1–8, or an image that isn't a PNG/JPEG/WebP/GIF data URL.
`TRANSCRIBE_DOWN / WIKIPDF_DOWN / N8N_UNAVAILABLE`	`502`	The primary provider and its fallbacks all failed. Safe to retry once; if it persists, the provider is down.
`CERT_UNAVAILABLE / IMGCHAT_DOWN`	`502`	Certificate generation or AI vision has no free fallback — the upstream API itself is unreachable. Retry later.
`ALLDL_DOWN / MAIL_DOWN`	`502`	The downloader or temporary-mail upstream is unreachable (the mail service is intermittently degraded). Retry later; do not hammer the endpoint.

Binary routes return JSON errors

Endpoints that return files on success — screenshots, PDFs, audio, generated images — return application/json when they fail. Never assume a 200 means bytes and never assume bytes without checking:

Check the content-type response header before parsing.
If it contains application/json, parse the body as the normalized error shape above.
Only treat the body as a file when the content-type is the expected media type (e.g. image/png).
On success, X-Provider and X-Fallback-Used headers tell you which backend served the file.

Retry guidance: retry once on 502 errors with a short delay. Don't retry 400s (fix the request instead) and don't retry 429s until the Retry-After window passes — see rate limits.

Back to the API quickstart.