Errors¶
All errors share the same envelope:
json
{
"ok": false,
"contractVersion": "1.0.0",
"error": { "code": "string", "message": "human-readable" }
}
Catalog¶
| HTTP | error.code |
When |
|---|---|---|
| 400 | invalid_json |
request body is not valid JSON |
| 400 | invalid_schema |
unknown top-level field, wrong type |
| 401 | unauthorized |
X-API-Key is missing or invalid |
| 413 | payload_too_large |
request body exceeds the transport limit |
| 413 | too_many_items |
piece or sheet count exceeds plan limit |
| 415 | unsupported_media_type |
Content-Type is not application/json |
| 422 | validation_failed |
domain rule violated (piece > sheet, kerf negative, ...) |
| 429 | rate_limit_exceeded |
per-second cap or daily/monthly quota hit |
| 500 | internal_error |
unexpected — please report with x-request-id |
Reading 422 messages¶
Validation messages are designed to be shown to your end users:
"validation_failed: piece[2] (1500x900) does not fit in any sheet (max 3210x2250 minus margins)"
If you receive a 422 and the message looks too cryptic for your domain, open an issue — we'll improve the wording.
Retrying¶
| Code | Retry? |
|---|---|
| 4xx (except 429) | ❌ — fix the request |
| 429 | ✅ — wait Retry-After seconds |
| 5xx | ✅ — exponential backoff, max 3 attempts |