API errors and rate limits

An ARUKZ ERP API error comes back as an HTTP status code with a JSON body holding a message, and for 422 an errors object naming each field that failed. Each user may make 120 requests a minute across the whole API; the next request in that minute gets 429. Send Accept: application/json, or some errors come back as a redirect or an HTML page instead.

Status codes

Code	Meaning	What to do
`200`, `201`	Done; `201` when a record was created	—
`401`	No token, or the token is wrong, expired or revoked	Get a new token
`402`	The company’s subscription is locked (trial ended, unpaid or suspended), or the company is read-only and the request tries to change something	The company’s admin pays or renews under Settings → Subscription; see Read-only mode
`403`	The user’s role does not allow this, the token is read-only and the request writes, the user is deactivated, or the module is switched off for the company	Use a user and role with the right permissions, a token with `write`, or ask ARUKZ to switch the module on
`404`	No such record, or the record belongs to another company or is outside what the user may see	Check the ID; records of other companies are never shown
`422`	The body failed validation, or a business rule refused it (for example no journal for the document)	Read `errors` and fix the fields
`429`	Too many requests	Wait for the minute to pass; see the limits below
`500`	Something failed on the server	Retry later; if it repeats, tell ARUKZ support the time and the endpoint

The error body

Validation errors name each field:

{
  "message": "The partner id field is required.",
  "errors": {
    "partner_id": ["The partner id field is required."]
  }
}

Other errors carry only the message:

{ "message": "This module is switched off for your company." }

Rate limits

What	Limit
Every API endpoint except sign-in	120 requests a minute per user (per address before sign-in)
`POST /admin/api/v1/login`	5 attempts a minute per address

The limit counts all of a user’s tokens together. A bulk import that needs more should page through its work and pause when it gets 429.

Company and permission checks

Every request is checked in this order: the token is valid; the user is active; the company is not locked (and, if read-only, the request only reads); the module is switched on; the token may write if the request writes; the user’s role allows the action; and the record belongs to the user’s company and is within their record visibility. The first check that fails decides the status code.

Get started

Endpoints

API errors and rate limits

Status codes

The error body

Rate limits

Company and permission checks