Errors & status codes
How the GoyConvert API reports errors and how to handle them.
Every error response is JSON with at least an error field, and the relevant
HTTP status code.
{ "error": "unsupported conversion", "supportedTargets": ["jpeg", "webp", "png"] }
Status codes
| Status | Meaning | What to do |
| --- | --- | --- |
| 400 | Validation failed (bad body, malformed inputKey, bad webhook URL) | Fix the request; see error for details |
| 401 | Missing or invalid API key | Check the Authorization: Bearer header |
| 403 | Bot-protection check failed (proof of work / Turnstile) | Solve the /challenge and retry |
| 404 | Job not found, or it belongs to another account | Use a job id your key created |
| 413 | File too large, or too many files in a batch | Reduce size / split the batch (see Limits) |
| 422 | The source → target pair isn't supported | Read supportedTargets, or call /formats |
| 429 | Rate limit exceeded | Back off and retry (see Retry-After) |
| 502 | Webhook delivery failed | The destination didn't return 2xx |
| 503 | A feature isn't configured on this deployment | — |
Conversion (job) errors
A conversion job can finish with status: "error" even though the request
succeeded. Poll GET /conversions/:id and check:
{ "id": "8f2b…", "status": "error", "error": "ImageMagick failed: …" }
Common causes: a corrupt or truncated input file, an input that exceeds the engine's resource limits, or a format whose delegate isn't installed.
Retries
429, 502 and transient 5xx are safe to retry with exponential backoff.
4xx validation errors (400, 413, 422) will not succeed on retry — fix the
request first. The SDK surfaces all of these as GoyConvertError with a .status.