Errors
Each error answer has the same body:
{ "error": { "code": "validation", "message": "Partner is missing.", "fields": { "subjectId": "Partner is missing." } }}| Member | Always | Contents |
|---|---|---|
code |
Yes | A stable code from the table below. Use it in your program. |
message |
Yes | A text for a person, in the language of the request. Do not parse it. |
fields |
No | For validation: the field path and the message of each field with an error. |
details |
No | Data that a client acts on, for some errors. |
Codes and statuses
Section titled “Codes and statuses”| Code | Status | When |
|---|---|---|
unauthenticated |
401 | No credential, or a key or a token that is not valid |
forbidden |
403 | The caller has no right for this action, this tenant or this route |
tenant_suspended |
403 | The tenant is suspended. Reads work, writes are refused. |
not_found |
404 | The tenant, the record or the route does not exist |
conflict |
409 | The record exists already, or a linked record blocks the write |
validation |
422 | The body is not valid: a missing or wrong field, or a body that is not JSON |
business_rule |
422 | The data is valid, but a rule of the ERP refuses the action |
rate_limited |
429 | Too many requests. Read Rate limits. |
internal |
500 | An error of the server. The server logs it. |
validation and business_rule both use 422. Use code to tell them apart.
Examples
Section titled “Examples”These answers come from the API with Accept-Language: en:
| Request | Status | Body |
|---|---|---|
No Authorization header |
401 | {"error":{"code":"unauthenticated","message":"No access."}} |
| A wrong API key | 401 | {"error":{"code":"unauthenticated","message":"Invalid API key."}} |
| A key of another tenant | 403 | {"error":{"code":"forbidden","message":"The API key is not valid for this company."}} |
| An unknown document ID | 404 | {"error":{"code":"not_found","message":"The document does not exist."}} |
A create with an id that exists |
409 | {"error":{"code":"conflict","message":"The record already exists."}} |
| A body that is not JSON | 422 | {"error":{"code":"validation","message":"The request body is not valid JSON."}} |
| A confirm of a confirmed document | 422 | {"error":{"code":"business_rule","message":"The document is already confirmed."}} |
| Over the rate limit | 429 | {"error":{"code":"rate_limited","message":"Too many requests. Try again later."}} |
Translated messages
Section titled “Translated messages”The API writes message and the texts in fields in one of three languages: Macedonian (mk), English (en) or Albanian (sq). It selects the language in this order:
- The cookie
posto-locale, when its value ismk,enorsq. - The
Accept-Languageheader: the known language with the highest weight. - Macedonian.
A program without a cookie and without Accept-Language gets Macedonian. Send the header to get English:
curl https://app.postoerp.com/api/v1/acme/sales/invoices/01a1d5a5-0000-7000-8000-000000000000 \ -H "Authorization: Bearer $POSTO_API_KEY" \ -H "Accept-Language: en"{ "error": { "code": "not_found", "message": "The document does not exist." } }The same request with Accept-Language: sq:
{ "error": { "code": "not_found", "message": "Dokumenti nuk ekziston." } }The code is the same in each language.
What to do with an error
Section titled “What to do with an error”| Code | Action |
|---|---|
unauthenticated |
Check the key or get a new token. Do not retry with the same credential. |
forbidden, tenant_suspended |
Do not retry. A person must change the access or the tenant. |
not_found |
Check the tenant slug, the path and the ID. |
conflict |
Read the record. A create with your own id that gets 409 can mean that the first try worked. |
validation, business_rule |
Show the message to the user, or fix the data. A retry of the same body gets the same answer. |
rate_limited |
Wait the seconds of Retry-After, then retry. |
internal |
Retry later, with a delay that grows. |