Guías

Errores y límites

Todos los errores tienen la misma forma, los límites son predecibles y las escrituras se pueden reintentar sin duplicar nada.

Formato de error#

Cualquier respuesta 4xx o 5xx trae un objeto error con un code estable (para tu código) y un message legible (para tus logs). Algunos errores agregan details:

400 Bad Request

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "details": {
      "formErrors": [],
      "fieldErrors": { "channel": ["Invalid enum value"] }
    }
  }
}

Códigos de estado#

Status	Cuándo	Qué hacer
400	JSON inválido (`invalid_json`) o validación fallida (`validation_error`, con el detalle por campo).	Corrige la solicitud. No reintentes igual.
401	Falta la API key, es inválida o fue revocada (`unauthorized`).	Revisa el header y la key.
401	La key venció (`api_key_expired`, con `details.expired_at`). Una key puede tener fecha de vencimiento; 7 días antes avisamos por correo a los owners y admins.	Crea una key nueva o rota esta antes de la fecha.
402	Se alcanzó un límite del plan (`plan_limit_exceeded`).	Revisa `details.upgrade_url`>.
402	Se agotaron los mensajes del período en Developer Free (`message_quota_exceeded`). Los mensajes que llegan se siguen guardando.	Lee `fix`: espera el período siguiente o sube a Developer. Ver Precios
403	Falta el scope, la IP no está permitida o el workspace está deshabilitado.	Agrega el scope a la key o revisa sus IPs.
404	El recurso no existe en este workspace.	Revisa el id.
409	Conflicto, por ejemplo una `Idempotency-Key` todavía en proceso.	Reintenta en unos segundos.
422	La solicitud es válida pero no se puede procesar (por ejemplo, `no_channel_connection`, o `invalid_sms_message` y `sms_sender_mismatch` al mandar un SMS).	Lee `message`: casi siempre falta configurar algo en el workspace.
429	Superaste el límite de solicitudes (`rate_limited`).	Espera y reintenta con backoff.
5xx	Error de heysteff.	Reintenta con backoff y la misma `Idempotency-Key`.

Límite de solicitudes#

Cada API key tiene un tope de solicitudes por ventana de 60 segundos que depende del plan del workspace:

Plan	Solicitudes por minuto, por key
Developer Free	100
Developer	2.000
Developer Platform	4.000

Cada respuesta trae el estado del límite en tres cabeceras:

X-RateLimit-Limit: el tope de tu key.
X-RateLimit-Remaining: lo que te queda en la ventana actual.
X-RateLimit-Reset: segundos Unix en que empieza la ventana siguiente.

Al pasarte, la API responde 429 rate_limited con Retry-After (segundos) hasta que empieza la ventana siguiente. Reintenta después de ese tiempo, con backoff exponencial y algo de azar (por ejemplo 1, 2, 4 y 8 segundos).

Aparte están los límites del plan del workspace, como los mensajes al mes. Esos responden 402 plan_limit_exceeded y no se resuelven reintentando.

Idempotencia#

Las operaciones que crean algo aceptan el header Idempotency-Key. Si repites una solicitud con la misma clave, recibes exactamente la misma respuesta que la primera vez (mismo status, mismo cuerpo) y no se crea nada nuevo.

Endpoint	Clave
`POST /v1/messages`, `POST /v1/campaigns`, `POST /v1/automation-flows/{id}/trigger`	Header `Idempotency-Key`, opcional.
`POST /v1/charges`, `POST /v1/refunds`	Header `Idempotency-Key`, obligatorio.
`POST /v1/events`	Campo `idempotency_key` del cuerpo.
`POST /v1/conversions`	Campo `external_ref` del cuerpo.

Usa una clave por operación lógica, por ejemplo pedido-1042-en-camino, no una por intento.
Si la primera solicitud todavía está en proceso, la segunda recibe 409 idempotency_conflict: reintenta en unos segundos.

Paginación#

Los listados devuelven páginas. limit va de 1 a 200 (50 por defecto).

Endpoint	Cómo avanzar
`GET /v1/conversations`, `GET /v1/conversations/{id}/messages`, `GET /v1/contacts`	Pasa `cursor=<cursor.next>` mientras `cursor.has_more` sea `true`.
`GET /v1/events`	Pasa `after_seq=<cursor.next_after_seq>`.
`GET /v1/reviews`	Usa `limit` y `offset`.

Montos y fechas#

Los montos van en unidades menores, como enteros: 1990 son 19,90 USD. En monedas sin decimales, como el peso chileno, 19990 son $19.990.
Las fechas van en ISO 8601 con zona: 2026-10-31T14:02:11Z.
Los teléfonos van en formato internacional: +56912345678.