Skip to main content
Every response reports the result on two levels:
  • The HTTP status code tells the kind of error: is the request invalid (400), is a permission missing (403), does the record not exist (404)?
  • ResultCode tells exactly what went wrong, e.g. 1002 the customer code is already used. All codes are listed on the Result codes page.

Error response

boolean
false for errors.
string
0000 on success. On failure, the code of the first error.
string
All error messages joined into one text, separated by spaces (English).
array
Code and Message for each error. Only present on failure.
string
Only on duplicate errors (a value that must be unique is already used, e.g. customer code 1002, product code 2002, document and voucher numbers, definition names): the ID of the record that already exists, so you can use it instead of creating a new one.
string
Only on 500 responses (0001). Send this value to Noyax support so the error can be found.
If a request has several validation errors, all of them are returned in one response. ResultCode is then the code of the first error; check the Errors list when you look for a specific error.
A duplicate error looks like this:
Base your integration logic on Code, not on the Message text. Message wording may be improved, but the meaning of a code never changes.

HTTP status codes

Order of checks

If a request has problems at different stages, the errors of the first stage are returned. Checks run in this order:
1

Token (401)

Is there a token, and are its signature and lifetime valid?
2

Headers (400)

Are X-UserID, X-CompanyID and X-PeriodID valid, and is the user assigned to the company?
3

Permission (403)

Does the key have the required read or write permission for the module?
4

Request limits (429)

Has the per-second or the daily request limit been exceeded?
5

Body format (400)

Can the JSON body be read?
6

Business rules (400 / 404)

Are the fields valid, and does the record exist and is it visible?

Malformed body errors

If the JSON body cannot be read (malformed JSON, an invalid date, text in a number field and so on), the API returns 400 with code 0002. The message contains the JSON path of the invalid field:

Unknown fields

A request body can contain only the fields of the endpoint’s request schema. A top-level field name that the endpoint does not have (a typo, an ID such as GroupDetailId1 where the field takes a name, a field that cannot be updated on that resource) is rejected with 400 and code 0002 on POST, PUT and PATCH; it is never silently ignored. Names are compared without regard to case. This also means a response body cannot be sent back unchanged as a PUT body when it contains fields that the request does not have; send only the request fields.

Handling errors

For Retry only 401 (after refreshing the token), 429 (after a second for the per-second limit, the next day for the daily limit) and 500. 400, 403 and 404 return the same result if the request is repeated unchanged.