Saltar al contenido
Desarrolladores
4 min de lectura

Errores e idempotencia

Cómo reporta Furcata las fallas y cómo reintentar de forma segura sin enviar un mensaje dos veces.

Compartir artículo

Cuando algo sale mal, Furcata responde con un cuerpo JSON que te dice qué pasó y te da una referencia que puedes citar a soporte. Cuando algo pudo haber salido bien pero no estás seguro, una clave de idempotencia te permite reintentar sin enviar un mensaje dos veces.

La respuesta de error

Todos los errores usan la misma forma, así que puedes manejarlos en un solo lugar.

  • status: el código de estado HTTP.
  • title: un nombre corto para el error.
  • message: una explicación segura y legible que puedes mostrar o registrar.
  • error y error_description: la misma información al estilo OAuth, para los clientes que la esperan.
  • correlationId: una referencia única para esta falla exacta. Cítala cuando contactes a soporte.
  • path: el endpoint que se llamó.
Una respuesta de error
{
  "title": "BadRequestError",
  "message": "recipients must contain at least 1 item",
  "status": 400,
  "correlationId": "00000000-0000-4000-8000-000000000000",
  "error": "BadRequestError",
  "error_description": "recipients must contain at least 1 item",
  "path": "/v0/account/acc_123/message"
}

Códigos de estado que verás

  • 400: la petición se entendió pero los datos no son válidos. Corrige la petición y vuelve a intentarlo.
  • 401: falta el token, expiró o no se acepta. Refréscalo y reintenta.
  • 403: tienes la sesión iniciada, pero tu rol no permite esta acción.
  • 404: la cuenta, el contacto o la suscripción no existe.
  • 409: la petición entra en conflicto con otra que ya está en curso. Consulta la sección de idempotencia más abajo.
  • 413: el cuerpo de la petición supera 1 MB.
  • 429: estás enviando demasiado rápido. Espera y reintenta.
  • 5xx: algo falló de nuestro lado. Reintenta con retroceso exponencial y cita el correlationId si sigue ocurriendo.

Las fallas internas nunca exponen trazas de pila ni detalles del proveedor. Recibes un mensaje simple más el ID de correlación, y el detalle se queda en nuestros registros.

Idempotencia: reintentar sin enviar dos veces

Las redes pierden respuestas. Si reintentas el envío de un mensaje después de un tiempo de espera agotado, podrías enviarlo dos veces. Agrega un encabezado Idempotency-Key y Furcata recordará el primer resultado y lo repetirá por ti.

  • La clave debe tener entre 16 y 128 caracteres, usando letras, dígitos, guion o guion bajo.
  • Usa una clave nueva para cada intención nueva, y la misma clave para cada reintento de esa intención.
  • Una clave se recuerda durante 24 horas.
  • Si la primera petición todavía se está ejecutando, un reintento con la misma clave recibe 409. Espera un momento y reintenta.
  • Si reutilizas una clave con un cuerpo diferente, la petición se rechaza en lugar de emparejarse en silencio.
Enviar un mensaje con una clave de idempotencia
curl -X POST https://api.furcata.com/v0/account/acc_123/message \
  -H "Authorization: Bearer YOUR_FURCATA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3c1a9e4b2d4c8fa1b6e0d5c9f2a7b3" \
  -d '{
    "recipients": ["+15555550100"],
    "body": "Your table is ready."
  }'

Reintenta solo lo que es seguro reintentar

Reintenta un 429 o un 5xx después de una breve espera, y siempre con la misma clave de idempotencia. No reintentes un 400, 401, 403 o 404 sin cambios: la petición fallará de la misma manera cada vez.

Próximos pasos

Consulta Límites de peticiones para ver los presupuestos exactos, y Mensajes para conocer el endpoint de envío que acepta una clave de idempotencia.