Errores

Un error responde un código de estado y un sobre JSON con dos campos: code, estable, para su programa, y detail, un mensaje para una persona en español que puede cambiar de redacción en cualquier momento. Decida por code, nunca por detail.

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

Todos los códigos

Estado	code	Significado
400	range_too_long	De date_from a date_to hay más de 92 días.
400	location_forbidden	Una location que no es una sede de la empresa.
400	(ninguno)	Un parámetro es inválido: ver abajo.
401	not_authenticated	No hay llave en Authorization: Bearer.
401	api_key_invalid	La llave no existe o fue revocada.
401	api_key_expired	La llave pasó su fecha de vencimiento.
401	company_suspended	La empresa está suspendida o cerrada.
403	api_not_included	El plan de la empresa no incluye el API.
404	not_found	Una página del Detalle después de la última.
429	throttled	Demasiadas peticiones para la llave, o demasiadas llaves inválidas desde la dirección. Lleva retry_after.
503	maintenance	Kabal está en mantenimiento. Lleva Retry-After.

Autenticación explica el 401 y el 403, Límites el 429 y el 503.

Un parámetro inválido

Cuando un parámetro no se puede leer (una fecha que no es fecha, un id que no es un UUID, date_to antes de date_from), el 400 no lleva code: es un mapa de cada parámetro equivocado a sus mensajes.

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

Su programa distingue las dos clases de 400 por la presencia de code. Ninguna vale la pena repetirla: corrija la llamada.

Qué repetir

Estado	¿Repetir?
400, 401, 403, 404	No. La misma llamada recibe la misma respuesta.
429	Sí, después de Retry-After segundos.
503 maintenance	Sí, después de Retry-After segundos.
502, 503 sin código, 504, un error de red	Sí, unas cuantas veces con una espera que crece. Una llamada solo lee, así que repetirla siempre es seguro.