Errors and limits

The format of an error message, all error codes, the rate limit per key and other limits.

Last updated: Need help? Contact support

The error format#

Every error has the same shape:

{
  "error": {"code": "E_SCOPE", "message": "Deze sleutel heeft de bevoegdheid invoices:read niet."},
  "request_id": "6f1c2a3e-0000-4000-8000-000000000000"
}

Use code in your program; message is an explanation for people (in English or Dutch) and may change. State the request_id (also in the x-request-id header) when you contact support.

Error codes#

HTTPCodeMeaning
400E_VALIDATIONInvalid input, for example a wrong limit, an invalid date or an unknown customer_id. message says what.
401E_AUTHKey missing, invalid, revoked or expired.
403E_SCOPEThe key does not have the required permission.
404E_UNKNOWNUnknown path.
404E_NOT_FOUNDThe shipment does not exist (or does not belong to this company).
405E_METHODWrong method; the Allow header says which ones work.
413E_TOO_LARGEThe body is larger than 64 KB.
429E_RATEToo many calls; see below.
500E_SERVERTemporary error on the server. Try again later.

Rate limit#

  • Every key has a limit per minute, by default 60 calls per minute, in fixed windows of one minute.
  • The x-ratelimit-limit header in every response gives your key's limit.
  • When you exceed it you get 429 with E_RATE and the header Retry-After: 60. Wait and try again.
  • Too many calls with an invalid key from the same address are also answered with 429 for a while.

Other limits#

LimitValue
Body size64 KB
limit per page1 to 200, default 50
Open transport requests per customer30
Active keys per company20
Webhooks per company10
Response time of your webhook address10 seconds

Log#

Per call INTEGALL only records the operation, the status, the duration and the key prefix, never the key itself or the content. The call log is deleted after 90 days.