> ## 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.

# Error Handling

> Understand and handle API errors

# Error Handling

The Nevatal API uses standard HTTP status codes and returns structured error responses.

## HTTP Status Codes

| Code  | Meaning                                                       |
| ----- | ------------------------------------------------------------- |
| `200` | Success                                                       |
| `201` | Created                                                       |
| `400` | Bad Request — Invalid parameters or validation error          |
| `401` | Unauthorized — Missing or invalid API key                     |
| `403` | Forbidden — API key lacks required scope                      |
| `404` | Not Found — Resource doesn't exist                            |
| `409` | Conflict — Resource already exists or state conflict          |
| `422` | Unprocessable Entity — Valid JSON but business rule violation |
| `429` | Too Many Requests — Rate limit exceeded                       |
| `500` | Internal Server Error — Something went wrong on our end       |

## Error response format

```json theme={null}
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Patient document number is required"
}
```

## Validation errors

When a request fails validation, the response includes details about which fields are invalid:

```json theme={null}
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed",
  "details": [
    {
      "field": "email",
      "message": "Invalid email format"
    },
    {
      "field": "phone",
      "message": "Phone number must be at least 10 digits"
    }
  ]
}
```

## Rate limiting

When rate limited, check the `Retry-After` header for the number of seconds to wait:

```
HTTP/1.1 429 Too Many Requests
Retry-After: 30
```

## Best practices

<Steps>
  <Step title="Always check status codes">
    Don't assume every response is successful. Check the HTTP status code before processing the body.
  </Step>

  <Step title="Implement retry logic">
    For `429` and `5xx` errors, implement exponential backoff retry logic.
  </Step>

  <Step title="Log error responses">
    Log the full error response body for debugging. The `message` field is human-readable.
  </Step>
</Steps>