> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nevatal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manejo de Errores

> Comprenda y maneje los errores de la API

# 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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Implemente lógica de reintentos">
    Para errores `429` y `5xx`, implemente una lógica de reintentos con retroceso exponencial (exponential backoff).
  </Step>

  <Step title="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.
  </Step>
</Steps>