API errors and status codes
What each HTTP status and error code from the Alya Books API means and how to react.
Every API error is a JSON body with the same shape, so one handler covers them all:
{ "code": "E_VALIDATION", "statusCode": 400, "message": "…", "field": "items", "extra": { … } }
code is the machine-readable reason, field points to the offending input when there is one, and extra carries details such as PINT AE errors or batch results.
Status codes
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | E_VALIDATION | The payload is invalid or the invoice fails PINT AE | Fix the field named in field; read extra.errors for business terms |
| 401 | UNAUTHORIZED | Missing, malformed, unknown, revoked or expired key | See the 401 article |
| 403 | FORBIDDEN | Key lacks the scope, or X-Organization-Id is not a managed client | Create a key with the right scopes |
| 404 | NOT_FOUND | No such invoice, import, customer or file | Check the id |
| 409 | CONFLICT | The action is not allowed in the current state, for example deleting an accepted invoice or reusing a SKU | Change the state first (archive instead of delete) |
| 413 | PAYLOAD_TOO_LARGE | Uploaded file over 20 MB | Split or compress |
| 422 | E_VALIDATION | A received document failed validation on import | The import is logged; read extra.validation |
| 429 | RATE_LIMITED | More than 600 requests per minute for this key | Wait for the seconds in Retry-After |
| 503 | SERVICE_UNAVAILABLE | A PDF of a received invoice's visualisation was requested where no HTML-to-PDF service is configured (invoice, credit note, debit note and proforma PDFs always work) | Request ?format=html or xml |
| 500 | INTERNAL_SERVER_ERROR | Unexpected failure | Retry; contact support@alyabooks.ai with X-Request-Id |
Batches
When one invoice in a batch fails, the response takes the status of the first failure (usually 400) and extra.results lists every element with index, success and its own error. Elements with success: true were created; retry only the others.
Good to know
- Every response carries
X-Request-Id, and error bodies repeat it asrequestId. The Recent requests tab on the API access page shows the same id under each request, with status and timing. - Webhook deliveries retry after at least 1 min, 5 min, 30 min, 2 h and 12 h (retries are sent by a job that runs every 5 minutes); the deliveries dialog shows attempts and lets you retry by hand.