Códigos HTTP y Errores

Para garantizar una integración predecible y robusta, la API de Vendis utiliza los códigos de estado estándar de HTTP para indicar el éxito o fracaso de una petición.

Adicionalmente, todas las respuestas de error devuelven un formato estructurado en formato JSON que permite a los desarrolladores automatizar el manejo de excepciones en su código.

Estructura Base de Errores

Todos los errores generados por la API (con excepción de algunos errores catastróficos de red) devuelven el siguiente formato base:

{
  "type": "api_error",
  "code": "internal_server_error",
  "message": "Error at the server."
}

Diccionario de Campos

• type (string): Clasificación general del error. Los valores comunes incluyen api_error, authentication_error, y validation_error.
• code (string): Un código corto y programático que tu sistema puede usar para tomar decisiones (ej. invalid_request_data, resource_not_found, unauthorized).
• message (string): Un mensaje descriptivo y legible diseñado para ayudar al desarrollador a entender qué salió mal.

---

Errores de Validación (HTTP 422)

Cuando una petición tiene la sintaxis correcta pero falla en las validaciones de negocio (por ejemplo, falta un campo obligatorio o un formato es incorrecto), la API devuelve un HTTP 422 Unprocessable Entity.

En este caso, la estructura base se expande para incluir un objeto errors, detallando exactamente qué falló en cada campo:

{
  "type": "validation_error",
  "code": "invalid_request_data",
  "message": "The given data was invalid.",
  "errors": {
    "amount": [
      "The amount must be a number.",
      "The amount must be greater than 0."
    ],
    "business_code": [
      "The business_code field is required."
    ]
  }
}

---

Resumen de Códigos HTTP

Éxito (2XX)

• 200 OK: La petición se realizó correctamente.
• 201 Created: La petición fue exitosa y como resultado se ha creado un nuevo recurso (por ejemplo, al generar un nuevo QR).

Errores del Cliente (4XX)

• 400 Bad Request: La petición no pudo ser entendida por el servidor debido a una sintaxis malformada (por ejemplo, enviaste un JSON roto o inválido).
• 401 Unauthorized: Es requerida una autenticación. Normalmente ocurre cuando no se envía la cabecera X-API-KEY o la llave proveída no es válida.
• 403 Forbidden: Tienes una llave válida, pero no tienes permisos suficientes para realizar esa acción específica.
• 404 Not Found: El recurso solicitado (ej. un qr_id específico) no existe en nuestros servidores.
• 422 Unprocessable Entity: Error de validación. El formato es correcto pero los datos violan las reglas de negocio. (Ver sección de Errores de Validación).

Errores del Servidor (5XX)

• 500 Internal Server Error: Ocurrió un problema de nuestro lado. El servidor no pudo procesar la petición. Si recibes esto de forma constante, por favor contacta a soporte técnico.