Error Handling
The Arratech API has two separate error systems. Understanding the difference is important, because if you only handle HTTP errors you will miss transaction failures entirely.
- AT-xxxx codes are synchronous HTTP errors returned immediately when an API call fails.
- TXE-1xxx codes are asynchronous transaction errors. They appear on a Transaction record when Peppol document exchange fails in the background. They are not HTTP errors.
AT-xxxx errors
AT-xxxx errors come back as HTTP 4xx or 5xx responses. Most carry a code in AT-xxxx format (a string, not a number) and an error with a human-readable description. Two cases differ: a 401 and a 403 from a superadmin-only operation carry only a message, and a 403 for an insufficient organisation role carries the code AR-01.
Check the HTTP status first. Then use the code for programmatic logic and the error for display or logging. The full list is in API Error Codes.
TXE-1xxx errors
TXE-1xxx errors are not HTTP errors. They appear in the serviceError field of a Transaction record when background Peppol document exchange fails. You will not see them on the initial API response. You have to check the transaction afterwards.
To detect a failure, check that transactionStatus is FAILED, then read serviceError. It holds a code, a message you can show directly to your customer, and a category. Each code also has an Action that says whether to retry, fix the input and retry, contact support, or stop and alert. The full list is in Transaction Processing Error Codes.
HTTP status codes to handle
The standard codes (400, 401, 403, 404, 500) behave as you would expect. Watch for these less obvious ones:
- 207 Multi-Status: returned by batch delete endpoints. The request as a whole succeeded, but individual items may have failed. Check each item's error in the response.
- 409 Conflict: a duplicate operation was attempted.
- 202 Accepted: an asynchronous operation has started. Poll the resource for its final status.
Error shape differences
Batch delete item errors differ from standard API errors. The code is numeric and the text is in message, not error. If you loop over a batch delete response, make sure your error handling covers both shapes.