Error Handling

The Arratech API has two separate error systems. Understanding the difference is important — 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 that appear on a Transaction record when Peppol document exchange fails in the background. They are not HTTP errors.

AT-xxxx errors

AT-xxxx errors are returned as HTTP 4xx or 5xx responses. Every error response has this shape:

{
  "code": "AT-1018",
  "error": "Unauthorised"
}
  • code is a string in AT-xxxx format — not a number.
  • error is a human-readable description.

Handle these by checking the HTTP status code first, then reading code for programmatic logic and error for display or logging.

For the full list of AT codes see API Error Codes in the API Reference.

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 these on the initial API response — you need to check the transaction after the fact.

A failed transaction's serviceError looks like this:

{
  "serviceError": {
    "code": "TXE-1005",
    "message": "The document could not be delivered to the recipient. This may be temporary — please retry.",
    "category": "TRANSPORT_ERROR"
  }
}
  • code — the TXE-1xxx code identifying the specific failure.
  • message — a human-readable explanation suitable to show directly to your customer, including a hint about what to do next.
  • category — classifies the type of failure (e.g. TRANSPORT_ERROR, VALIDATION_ERROR).

To detect a failure: check transactionStatus === 'FAILED', then read serviceError.

Each TXE code has an associated Action value that tells you how to respond:

  • RETRY — the failure is likely temporary; safe to retry automatically.
  • FIX_AND_RETRY — the customer needs to correct something before retrying.
  • CONTACT — escalate to support.
  • DO_NOT_RETRY — security concern; stop and alert.

For the full list of TXE codes and their Action guidance, see Transaction Processing Error Codes in the API Reference.

HTTP status codes to handle

Standard codes (400, 401, 403, 404, 500) behave as expected. Pay attention to these less obvious ones:

  • 207 Multi-Status — returned by batch delete endpoints. The request as a whole succeeded, but individual items may have failed. Iterate each item in the response and check its error individually.
  • 409 Conflict — a duplicate operation was attempted.
  • 202 Accepted — an asynchronous operation has been started. Poll the resource for its final status.

Error shape differences

Standard API errors use { "code": string, "error": string }. Batch delete item errors use a slightly different shape: code is numeric and the message field is message, not error. If you are iterating a batch delete response, make sure your error-handling code accounts for this difference.