Errores

Todos los errores tienen la misma forma y un code estable. Decide qué hacer con code, nunca con message: los mensajes son para personas y pueden cambiar.

{
  "error": {
    "code": "INSTANCE_NOT_CONNECTED",
    "message": "The instance is not connected. Connect it before sending messages.",
    "request_id": "req_01EXAMPLEEXAMPLEEXAMPLE0"
  }
}

request_id identifica la petición: cítalo cuando contactes a soporte. Los errores de validación añaden los campos que fallaron:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The request is invalid.",
    "request_id": "req_01EXAMPLEEXAMPLEEXAMPLE0",
    "details": { "fields": { "name": ["The name field is required."] } }
  }
}

Errores que cualquier operación puede devolver

Estado	Código	Significado
400	WORKSPACE_MISMATCH	El header X-Zappio-Workspace nombra otro espacio de trabajo.
401	UNAUTHENTICATED	Falta el header Authorization: Bearer.
401	INVALID_API_KEY	La clave no existe o fue revocada.
403	INSUFFICIENT_SCOPE	La clave no tiene el scope de la operación.
403	WORKSPACE_SUSPENDED	El espacio de trabajo está suspendido.
404	NOT_FOUND	La ruta no existe (los recursos desconocidos usan los códigos específicos de abajo).
405	METHOD_NOT_ALLOWED	La ruta no admite ese método.
413	PAYLOAD_TOO_LARGE	El cuerpo de la petición supera el límite del servidor.
422	VALIDATION_FAILED	Falta un campo o es inválido (details.fields).
429	RATE_LIMITED	Demasiadas peticiones; ver Rate limits.
500	INTERNAL_ERROR	Falla inesperada; reintenta más tarde y cita el request_id.

Errores de operaciones específicas

Estado	Código	Dónde	Significado
402	TRIAL_LIMIT_REACHED	enviar mensaje	Se usaron los mensajes de la prueba.
402	SUBSCRIPTION_REQUIRED	enviar mensaje, crear instancia	El espacio de trabajo necesita una suscripción activa.
402	SUBSCRIPTION_PAST_DUE	enviar mensaje	El último pago falló y terminó el periodo de gracia.
403	INSTANCE_LIMIT_REACHED	crear instancia	Se alcanzó el límite de instancias del plan.
403	WEBHOOK_LIMIT_REACHED	crear webhook	Se alcanzó el límite de webhooks del plan.
404	INSTANCE_NOT_FOUND	cualquier operación con una instancia	No existe esa instancia en tu espacio de trabajo.
404	MESSAGE_NOT_FOUND	consultar mensaje, multimedia	No existe ese mensaje.
404	GROUP_NOT_FOUND	enviar mensaje	El id grp_ no es un grupo de esa instancia.
404	MEDIA_NOT_AVAILABLE	multimedia	El mensaje no tiene un archivo guardado.
404	WEBHOOK_NOT_FOUND, WEBHOOK_DELIVERY_NOT_FOUND	webhooks	No existe ese webhook o esa entrega.
409	INSTANCE_NOT_CONNECTED	enviar mensaje	La instancia no está conectada.
409	INVALID_INSTANCE_STATE	conectar, desconectar, cerrar sesión	La transición no está permitida desde el estado actual.
409	INSTANCE_BUSY	conectar, desconectar, cerrar sesión, eliminar	Hay otra operación en curso sobre la instancia; reintenta.
409	QR_NOT_AVAILABLE	QR	La instancia no está esperando vincularse.
409	WEBHOOK_DISABLED	probar, reintentar	El webhook está deshabilitado; habilítalo primero.
409	WEBHOOK_RETRY_NOT_ALLOWED	reintentar entrega	La entrega sigue en curso, o su webhook está deshabilitado o eliminado.
415	INVALID_MEDIA_TYPE	enviar mensaje	El formato no se acepta para ese tipo de mensaje.
413	MEDIA_TOO_LARGE	enviar mensaje	El archivo supera el límite de ese tipo.
422	INVALID_RECIPIENT	enviar mensaje	to no es un número internacional ni un id de grupo.
422	UNSUPPORTED_MESSAGE_TYPE	enviar mensaje	El tipo es desconocido o la instancia no puede enviarlo.
422	INVALID_IDEMPOTENCY_KEY	enviar mensaje	El header Idempotency-Key tiene un formato inválido.
422	IDEMPOTENCY_KEY_REUSED	enviar mensaje	La clave ya se usó con una petición distinta.
422	INVALID_WEBHOOK_URL	crear o editar webhook	La URL no está permitida (esquema, puerto o host).
429	SEND_BACKLOG	enviar mensaje	La instancia tiene demasiados mensajes esperando; reintenta tras Retry-After.
502 / 503	GATEWAY_ERROR, GATEWAY_UNAVAILABLE	conectar, desconectar, cerrar sesión, eliminar	El servicio de mensajería falló o no está disponible; reintenta más tarde.

Los errores de cada operación también aparecen en la referencia.

Qué hacer según el estado

• 4xx: el problema está en la petición. Corrígela; reintentar igual no ayuda (salvo 429 y 409 INSTANCE_BUSY).
• 429: espera Retry-After segundos.
• 5xx: falla del lado de ZAPPIO. Reintenta con espera creciente y, si persiste, escribe a soporte con el request_id. Para envíos, reintenta con la misma Idempotency-Key.