Errors

An error answers a status code and a JSON envelope with two fields: code, stable, for your program, and detail, a message for a person in Spanish that can change wording at any time. Branch on code, never on detail.

{ "detail": "El rango no puede pasar de 92 días.", "code": "range_too_long" }

Every code

Status	code	Meaning
400	range_too_long	date_from to date_to spans more than 92 days.
400	location_forbidden	A location that is not a site of the company.
400	(none)	A parameter is invalid: see below.
401	not_authenticated	No key in Authorization: Bearer.
401	api_key_invalid	The key does not exist or was revoked.
401	api_key_expired	The key passed its expiry date.
401	company_suspended	The company is suspended or closed.
403	api_not_included	The company's plan has no API.
404	not_found	A page of the detail past the last one.
429	throttled	Too many requests for the key, or too many invalid keys from the address. Carries retry_after.
503	maintenance	Kabal is in maintenance. Carries Retry-After.

Authentication explains the 401 and 403, Limits the 429 and 503.

An invalid parameter

When a parameter cannot be read (a date that is not a date, an id that is not a UUID, date_to before date_from), the 400 has no code: it is a map from each wrong parameter to its messages.

{ "date_to": ["El fin es anterior al inicio."] }

Your program can tell the two kinds of 400 apart by the presence of code. Neither kind is worth retrying: fix the call.

What to retry

Status	Retry?
400, 401, 403, 404	No. The same call gets the same answer.
429	Yes, after Retry-After seconds.
503 maintenance	Yes, after Retry-After seconds.
502, 503 without a code, 504, a network error	Yes, a few times with a growing wait. A call only reads, so repeating it is always safe.