Errores y recuperación

Forma de error

Los errores incluyen un mensaje y, cuando existe un código estable, un objeto error. Los errores de validación de Laravel exponen además un mapa errors por campo.

HTTP 402

{
  "message": "A usable Nuntia subscription is required for this operation.",
  "error": {
    "code": "billing_required",
    "reason": "subscription_missing",
    "subscription_status": null
  }
}

Estados relevantes

400 Solicitud no interpretable Revisa JSON, headers y formato.

401 Autenticación ausente o inválida Verifica workspace y secreto sin imprimirlos.

402 billing_required El workspace no tiene un acceso utilizable o está bajo hold.

403 Operación no autorizada El recurso o acción no pertenece al contexto permitido.

404 Recurso no visible El ID no existe dentro del workspace autenticado.

409 Conflicto de estado La operación no aplica al estado actual.

422 Validación o regla de negocio Corrige los campos indicados o el bloqueo funcional.

429 authentication_rate_limited Respeta Retry-After antes de reintentar autenticación.

502 Proveedor rechazó el envío Consulta data.error y la traza antes de decidir retry.

Política de reintento

No reintentes automáticamente 401, 402, 403 o 422; primero corrige su causa.
Para 429, respeta Retry-After y usa backoff con jitter.
Ante 502, consulta el mensaje por su ID cuando haya sido persistido y evita duplicar efectos con una referencia estable.
Los callbacks pueden repetirse: deduplica siempre por event_id.

Soporte con evidencia útil

Comparte el ID público del mensaje, client_reference, timestamp y código normalizado. Nunca envíes el secreto API, el secreto del webhook, tokens Meta ni números completos en capturas.