Errores y límites

La forma de un error

message es para vos, leyendo logs. message_code es la clave estable contra la que conviene ramificar: no cambia aunque el texto sí.

request_id identifica ese pedido puntual. Guardalo en tus logs y pasánoslo si algo no cierra.

{
  "message": "El teléfono ya pertenece a otro contacto.",
  "message_code": "contact_exists",
  "request_id": "01M2XEM2ESR7K9A0AR29EDT9WJ",
  "contact_id": "01M2XEM2ESR7K9A0AR29EDT9WJ"
}

Los códigos

• 400: el cuerpo no es JSON válido.
• 401: falta la clave o no sirve.
• 402: la cuenta no está activa (account_not_active), está bloqueada porque la prueba terminó sin carga de saldo (tenant_locked) o está suspendida.
• 403: la clave no tiene ese permiso.
• 404: no existe, o no es de esta cuenta.
• 409: el teléfono ya pertenece a otro contacto.
• 422: el cuerpo no pasó la validación; mirá errors.
• 429: demasiados pedidos.
• 503: la telefonía de la cuenta todavía no está lista.

Límites

120 pedidos por minuto por clave, y un techo por cuenta por encima de eso, así que repartir la carga entre varias claves no compra más cupo.

Las importaciones tienen su propio cupo, más chico, porque un pedido puede traer miles de filas.

Cada respuesta te dice cuánto te queda, y un 429 te dice cuántos segundos esperar.

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
Retry-After: 37

Paginación

Las listas se paginan por cursor y vienen del más nuevo al más viejo. Seguí meta.next_cursor hasta que venga vacío; no hay número de página ni total, justamente para que una lista que crece mientras la recorrés no te repita ni te saltee filas.

Versiones

La versión va en la URL. Agregar campos a una respuesta, valores nuevos a un enum o parámetros opcionales nuevos no cambia la versión: tu integración tiene que ignorar lo que no conoce.

Un cambio que rompa algo estrena /v2 y /v1 sigue andando.

Reintentos

No hay encabezado de idempotencia. En su lugar, la unicidad del teléfono hace que un alta repetida responda 409 en vez de crear un duplicado, y el upsert por external_id es idempotente por construcción: reintentarlo es seguro.

Ante un 429 o un 5xx, esperá lo que diga Retry-After y reintentá con espera creciente.