Ir al contenido

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.

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

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.

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.

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
  • 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-After y vuelve a intentarlo. Para no llegar al límite, vigila X-RateLimit-Remaining y espera X-RateLimit-Reset segundos 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-Key da 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.