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ódigo	Significado
`200`	Éxito (Success)
`201`	Creado (Created)
`400`	Solicitud Incorrecta (Bad Request) — Parámetros inválidos o error de validación
`401`	No Autorizado (Unauthorized) — Clave de API faltante o inválida
`403`	Prohibido (Forbidden) — La clave de API no tiene los permisos necesarios
`404`	No Encontrado (Not Found) — El recurso no existe
`409`	Conflicto (Conflict) — El recurso ya existe o hay un conflicto de estado
`422`	Entidad No Procesable (Unprocessable Entity) — JSON válido pero viola una regla de negocio
`429`	Demasiadas Solicitudes (Too Many Requests) — Límite de tasa excedido
`500`	Error 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

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.

Implemente lógica de reintentos

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

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.

Primeros Pasos

Conceptos Clave

Manejo de Errores

Manejo de Errores

Códigos de Estado HTTP

Formato de respuesta de error

Errores de validación

Límite de tasa (Rate Limiting)

Mejores prácticas

​Manejo de Errores

​Códigos de Estado HTTP

​Formato de respuesta de error

​Errores de validación

​Límite de tasa (Rate Limiting)

​Mejores prácticas

Manejo de Errores

Códigos de Estado HTTP

Formato de respuesta de error

Errores de validación

Límite de tasa (Rate Limiting)

Mejores prácticas