Errors
Every error response is JSON: { "error": "machine_code", "message": "human-readable", "issues"?: [...] }. issues is present only on validation_error, one entry per invalid field.
| HTTP | error code | Meaning |
|---|---|---|
| 400 | validation_error | Request body failed validation: check issues for which field. |
| 401 | missing_api_key / invalid_api_key | No x-api-key header, or the key doesn't match a live account. |
| 403 | plan_required | Your Pro or Developer plan has lapsed — renew to restore API/MCP access. Every active plan (Free, Pro, Developer) includes some level of API access, so this only fires on a lapsed subscription. |
| 402 | free_limit_reached | Free-plan trial: you've used all 50 lifetime credits (shared with the web app). Upgrade to Pro or Developer for a real recurring monthly quota. |
| 429 | api_quota_exceeded | You've used your monthly API/MCP generation quota (200/mo on Pro, 900/mo on Developer). Resets next billing period; upgrade for a higher limit. |
| 403 | forbidden | That job/batch id exists but belongs to a different account. |
| 404 | diagram_not_found | Diagram id doesn't exist, or belongs to a different account. |
| 404 | not_found | Job or batch id doesn't exist (or has been cleaned up). |
| 402 | insufficient_credits | /logo only: your credit balance can't cover this generation. |
| 429 | rate_limited | Too many requests. See Authentication & concepts, retry after RateLimit-Reset. |
| 503 | image_service_unavailable / batch_unavailable | Generation is temporarily unavailable, retry shortly. |
| 500 | various *_failed codes | An unexpected server-side failure. Safe to retry; contact support if it persists. |
Full field-by-field spec: /api/v1/openapi.json