Saltar al contenido principal

​
Manejo de Errores

La API de Nevatal utiliza códigos de estado HTTP estándar y devuelve respuestas de error estructuradas.

​
Códigos de Estado HTTP

CódigoSignificado
200Éxito (Success)
201Creado (Created)
400Solicitud Incorrecta (Bad Request) — Parámetros inválidos o error de validación
401No Autorizado (Unauthorized) — Clave de API faltante o inválida
403Prohibido (Forbidden) — La clave de API no tiene los permisos necesarios
404No Encontrado (Not Found) — El recurso no existe
409Conflicto (Conflict) — El recurso ya existe o hay un conflicto de estado
422Entidad No Procesable (Unprocessable Entity) — JSON válido pero viola una regla de negocio
429Demasiadas Solicitudes (Too Many Requests) — Límite de tasa excedido
500Error Interno del Servidor (Internal Server Error) — Algo salió mal de nuestro lado

​
Formato de respuesta de error

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "El número de documento del paciente es obligatorio"
}

​
Errores de validación

Cuando una solicitud falla la validación, la respuesta incluye detalles sobre qué campos son inválidos: 
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "La validación falló",
  "details": [
    {
      "field": "email",
      "message": "Formato de correo electrónico inválido"
    },
    {
      "field": "phone",
      "message": "El número de teléfono debe tener al menos 10 dígitos"
    }
  ]
}

​
Límite de tasa (Rate Limiting)

Cuando se alcanza el límite de tasa, verifique el encabezado Retry-After para saber cuántos segundos debe esperar: 
HTTP/1.1 429 Too Many Requests
Retry-After: 30

​
Mejores prácticas

1

Siempre verifique los códigos de estado

No asuma que cada respuesta es exitosa. Verifique el código de estado HTTP antes de procesar el cuerpo de la respuesta.
2

Implemente lógica de reintentos

Para errores 429 y 5xx, implemente una lógica de reintentos con retroceso exponencial (exponential backoff).
3

Registre las respuestas de error

Registre el cuerpo completo de la respuesta de error para la depuración. El campo message es legible por humanos.