Errors

Successful requests return 200. A failed request returns a 4xx or 5xx status and a JSON body that says why.

The error body

{
  "message": "The transaction date falls in a closed period.",
  "code": "closed_period"
}

message is always present and is safe to show to a person.
code is present when the failure has a known cause. Branch on code, never on the wording of message: messages may be reworded or translated.
Some errors add detail fields. For example, a missing required custom field adds a fields array listing the keys.

A few older endpoints return { "error": "…" } instead of message. The reference marks those responses. Treat error the same way as message.

Status codes

Status	Meaning	What to do
`400`	The request is invalid: a missing or malformed field, an unknown vendor, a value too long.	Fix the request. Don’t retry it unchanged.
`401`	The API key is missing, wrong, inactive or expired.	Check the `X-API-Key` header.
`403`	The key is valid, but its user may not do this: no access to the dataset, a missing permission, or approval rules that forbid it.	Adjust the user’s role, or send a draft instead.
`404`	The record doesn’t exist in this dataset.	Check the id and the `{vc}` side.
`409`	The record is in a state that doesn’t allow this, for example approving something already approved.	Re-read the record and decide.
`422`	The date falls in a closed period.	Use a date after the period close, or ask the accountant.
`423`	The record is owned by another integration and can only be changed there.	Change it in the source system.
`5xx`	Something failed on our side.	Retry later with backoff. If it persists, contact Support with the time of the request.

Codes when posting a transaction

These are the codes POST /arap/transaction/{vc} can return. They are the ones most integrations need to handle.

`code`	Status	Meaning
`vc_not_found`	400	The `vendornumber` or `customernumber` matched nobody.
`project_not_found`	400	A line’s `project` matched no project.
`missing_required_custom_fields`	400	A custom field marked required has no value. `fields` lists which.
`amount_exceeded`	400	You asked to approve, but the total is above what this user may approve.
`no_amount_rules`	400	You asked to approve, but no approval rule allows this user to. Send a draft instead.
`file_upload_failed`	400	The transaction was saved, but an attachment could not be stored. See the note below.
`access_denied`	403	You asked to approve, but the user has no workstation access for this side.
`post_not_allowed`	403	Posting is switched off for this user on this side.
`expense_managed`	409	The transaction belongs to an expense. Handle it from Expenses in the app.
`closed_period`	422	The date falls in a closed period.
`integration_locked`	423	Another integration owns this transaction.

file_upload_failed is the one error where the transaction was saved, and the response carries no id. Don’t resend the transaction, or you will book the bill twice. Find it with GET /arap/transactions/{vc}?document_number=… and attach the file to it in the app.