Skip to content

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.
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.

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."}}

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:

  1. The cookie posto-locale, when its value is mk, en or sq.
  2. The Accept-Language header: the known language with the highest weight.
  3. Macedonian.

A program without a cookie and without Accept-Language gets Macedonian. Send the header to get English:

Terminal window
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.

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.