API Firmaris - Códigos de Error

Esta sección explica todos los errores que puede devolver la API Firmaris, qué significan y qué debe hacer el integrador para solucionarlos.

El objetivo es que cualquier persona, incluso sin experiencia técnica avanzada, pueda entender:

• Qué ocurrió
• Por qué ocurrió
• Qué acción debe tomar

---

Resumen de Códigos de Estado HTTP

La API Firmaris utiliza códigos de estado HTTP estándar para indicar el resultado de cada solicitud.

Código	Estado	Significado	Ejemplo común
400	Bad Request	Los datos enviados son incorrectos, incompletos o no cumplen el formato esperado	Parámetro obligatorio faltante, JSON inválido
401	Unauthorized	No se envió el token de autenticación requerido	Header x-api-key no enviado
403	Forbidden	El token es inválido, está vencido o no tiene permisos suficientes	Acceso denegado a un recurso
404	Not Found	El recurso solicitado no existe o no pertenece a la empresa autenticada	Folio inexistente
409	Conflict	El recurso se encuentra en un estado que impide la operación	Folio ya firmado o rechazado
410	Gone	El recurso ya no está disponible	Folio vencido
429	Too Many Requests	Se excedió el límite de solicitudes permitidas	Demasiadas peticiones en poco tiempo
500	Internal Server Error	Error interno del sistema	Falla inesperada al procesar la solicitud

---

Estructura General de Respuesta de Error

Todas las respuestas de error siguen una estructura consistente.

{
  "success": false,
  "status": 400,
  "message": "Descripción general del error",
  "error": {
    "message": "Detalle específico del error",
    "details": "Información adicional (opcional)"
  }
}

Campos explicados

• success: Siempre es false cuando ocurre un error.
• status: Código HTTP del error.
• message: Explicación general del problema.
• error.message: Detalle específico del error.
• error.details: Información adicional para depuración.

---

400 - Bad Request (Parámetros inválidos)

Ocurre cuando los datos enviados no cumplen con el formato o las reglas esperadas.

Ejemplos comunes

{
  "success": false,
  "status": 400,
  "error": {
    "message": "El parámetro {field} es obligatorio."
  }
}

{
  "success": false,
  "status": 400,
  "error": {
    "message": "El parámetro signers no contiene un formato json válido."
  }
}

{
  "success": false,
  "status": 400,
  "error": {
    "message": "El parámetro email de los firmantes no contiene un formato de correo electrónico válido."
  }
}

---

401 - Unauthorized

Este error aparece cuando no se envía el token de autenticación.

{
  "success": false,
  "status": 401,
  "message": "Autenticación requerida"
}

Qué hacer

• Enviar el header x-api-key
• Usar el formato correcto: Bearer {TOKEN_EMPRESA}

---

403 - Forbidden (Acceso denegado)

El token es inválido, está vencido o no tiene permisos suficientes.

{
  "success": false,
  "status": 403,
  "message": "Acceso denegado. No tiene los permisos necesarios para acceder a este recurso."
}

---

404 - Not Found

El recurso solicitado no existe o no pertenece a la empresa autenticada.

{
  "success": false,
  "status": 404,
  "message": "El recurso al que intenta acceder no existe."
}

---

409 - Conflict

El recurso se encuentra en un estado que impide la operación.

{
  "success": false,
  "status": 409,
  "message": "El folio ya fue firmado o rechazado."
}

---

410 - Gone

El recurso ya no está disponible.

{
  "success": false,
  "status": 410,
  "message": "El folio se encuentra vencido."
}

---

429 - Too Many Requests

Se superó el límite de solicitudes permitidas.

{
  "success": false,
  "status": 429,
  "message": "Ha excedido el límite de solicitudes permitidas."
}

---

500 - Internal Server Error

Error interno del sistema.

{
  "success": false,
  "status": 500,
  "message": "Se ha producido un error interno, inténtelo de nuevo."
}

---

Recomendaciones Generales

• Valida los datos antes de enviar la solicitud.
• Maneja los errores usando el código HTTP.
• Registra el status y message para diagnóstico.
• Si el error persiste, contacta al soporte técnico de Firmaris.