Errores y límites de uso
El formato de los errores de la API de Bookline, qué significa cada código, los límites de peticiones y cuándo reintentar.
Formato de los errores
Sección titulada «Formato de los errores»Todos los errores tienen el mismo cuerpo: un code estable, pensado para tu código, y un message legible que explica la causa.
{ "error": { "code": "range_too_large", "message": "at most 31 days for granularity=day" } }available_from solo aparece en un not_found causado por agentes que cambiaron de cuenta (consulta las reglas de los datos).
Códigos de error
Sección titulada «Códigos de error»| Estado | Código | Cuándo | Qué hacer |
|---|---|---|---|
| 400 | invalid_query |
Falta un parámetro, tiene un formato incorrecto o el endpoint no lo admite; un cursor de otra consulta; o un POST sin Idempotency-Key |
Corrige la petición; el mensaje indica el parámetro |
| 400 | range_too_large |
Rango de más de 31 días (day) o 92 días (total) en métricas, o de más de 31 días en llamadas, chats o reservas |
Divide el rango |
| 400 | industry_ambiguous |
El cliente tiene agentes de restaurante y de hotel | Indica industry |
| 400 | customer_ambiguous |
La clave lee varios clientes | Indica customer_id |
| 400 | granularity_not_supported |
granularity=day en survey-ratings |
Usa total |
| 401 | invalid_api_key |
Clave ausente, desconocida, revocada o caducada | Revisa la cabecera apikey |
| 403 | insufficient_scope |
Cliente o local fuera del acceso de la clave, una ruta para la que la clave no tiene permiso, una ruta de todo el cliente con una clave limitada a algunos locales, o una escritura que el propietario de la clave no puede hacer | Revisa customer_id / venue_ids, los permisos de la clave o el acceso de su propietario; el mensaje indica cuál |
| 404 | venue_not_found |
Un id de venue_ids no es de ese cliente |
Usa los ids de GET /venues |
| 404 | not_found |
Recurso no disponible para el sector del cliente, sin datos antes de available_from, o un id que no es de tu cliente |
Cambia de endpoint, empieza el rango en available_from o revisa el id |
| 409 | conflict |
Una escritura que los datos no permiten (un contacto duplicado, una base de conocimiento que todavía usa un local…), o un Idempotency-Key reutilizado o todavía sin resolver |
Lee el mensaje; consulta Escribir datos |
| 412 | precondition_failed |
La versión de If-Match no es la actual: el recurso cambió desde que lo leíste |
Vuelve a leerlo y reenvía con el nuevo ETag |
| 413 | validation_failed |
El cuerpo ocupa más de 865.536 bytes | Envía un cuerpo más pequeño |
| 422 | validation_failed |
El cuerpo tiene un campo que la ruta no admite, o un valor fuera de sus reglas | Corrige el campo que indica el mensaje |
| 428 | precondition_required |
Un PATCH o un DELETE sin If-Match |
Envía el ETag del recurso como If-Match |
| 429 | rate_limited |
Por encima del límite de la clave: 60 lecturas, 10 escrituras o 30 peticiones de datos personales por minuto | Espera los segundos de Retry-After |
| 502 | upstream_error |
Error interno | Vuelve a intentarlo más tarde |
| 503 | upstream_busy |
Demasiadas peticiones a la vez | Vuelve a intentarlo en unos segundos |
| 504 | upstream_timeout |
La petición ha tardado demasiado | Vuelve a intentarlo con un rango más corto |
Los permisos de una clave no se pueden cambiar: si un insufficient_scope se debe a que falta un permiso, crea una clave nueva con él. Consulta Claves y permisos.
Límite de uso
Sección titulada «Límite de uso»Cada clave tiene estos límites por minuto. Cuentan todas las peticiones, también las fallidas.
| Peticiones | Límite por clave |
|---|---|
Lecturas (GET) |
60 por minuto |
Escrituras (POST, PATCH, DELETE) |
10 por minuto |
| Datos personales, además | 30 por minuto |
El límite de datos personales se aplica, además de los otros dos, a las rutas que devuelven datos personales: llamadas, chats, reservas, contactos, equipo, cuentas de facturación y valoraciones de encuestas, y a las escrituras que devuelven un contacto o un miembro del equipo. Las cabeceras X-RateLimit-* reflejan el límite más ajustado que se aplica.
Cabeceras de respuesta
Sección titulada «Cabeceras de respuesta»| Cabecera | Cuándo | Qué indica |
|---|---|---|
X-RateLimit-Limit |
Respuestas correctas | Peticiones permitidas en la ventana |
X-RateLimit-Remaining |
Respuestas correctas | Peticiones que te quedan en la ventana |
X-RateLimit-Reset |
Respuestas correctas | Segundos hasta que se reinicia la ventana |
Retry-After |
429 rate_limited |
Segundos que hay que esperar antes de volver a llamar |
X-Request-Id |
Todas las respuestas | Identificador de la petición |
ETag |
Lecturas del detalle y escrituras de los recursos que puedes cambiar | La versión que tienes que enviar como If-Match |
Idempotent-Replayed |
Un POST reenviado con el mismo Idempotency-Key |
true: la respuesta es la de la primera petición, no se ha creado nada dos veces |
Cuándo reintentar
Sección titulada «Cuándo reintentar»- 4xx (salvo 429): no reintentes la misma petición. El problema está en la petición o en la clave, y volverá a fallar igual: corrígela según la tabla.
- 429: espera los segundos de
Retry-Aftery vuelve a intentarlo. Para no llegar al límite, vigilaX-RateLimit-Remainingy esperaX-RateLimit-Resetsegundos cuando llegue a cero. - 502 y 503: vuelve a intentarlo pasados unos segundos, dejando cada vez más tiempo entre intentos.
- 504: la petición ha tardado demasiado; en las métricas, reintenta con un rango más corto.
- 412: vuelve a leer el recurso y reenvía la escritura con el nuevo
ETag. - Una escritura que termina en 502, 503 o 504 puede haberse aplicado. Lee el recurso (o lístalo, si era una creación) antes de volver a enviarla; una creación reenviada con el mismo
Idempotency-Keyda 409, nunca una segunda creación. Consulta Escribir datos.
Como los reintentos también cuentan para el límite, no reintentes en bucle sin esperar.
