> For the complete documentation index, see [llms.txt](https://docs.halfred.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.halfred.ai/04-api-reference/02-errors.md).

# Error Handling

Complete guide to Halfred API error responses, HTTP status codes, common errors, and best practices for error handling.

## Error Response Format

All errors follow a consistent JSON format:

```json
{
  "error": {
    "message": "Human-readable error description",
    "type": "error_category",
    "param": "parameter_that_caused_error",
    "code": "specific_error_code"
  }
}
```

### Response Fields

| Field           | Type   | Description                                     |
| --------------- | ------ | ----------------------------------------------- |
| `error.message` | string | Human-readable error description                |
| `error.type`    | string | Category of error                               |
| `error.param`   | string | Parameter that caused the error (if applicable) |
| `error.code`    | string | Specific error code for programmatic handling   |

## HTTP Status Codes

| Status Code | Meaning               | When It Occurs                              |
| ----------- | --------------------- | ------------------------------------------- |
| 200         | Success               | Request completed successfully              |
| 400         | Bad Request           | Invalid request parameters                  |
| 401         | Unauthorized          | Missing or invalid API key                  |
| 403         | Forbidden             | API key lacks required permissions          |
| 404         | Not Found             | Resource doesn't exist                      |
| 429         | Too Many Requests     | Rate limit exceeded or insufficient credits |
| 500         | Internal Server Error | Unexpected server error                     |
| 503         | Service Unavailable   | Temporary service outage                    |

## Frequently Asked Questions

### Should I retry all failed requests?

No. Retry only transient errors (5xx, 429). Don't retry client errors (4xx) except rate limits.

### What if I keep getting 500 errors?

Check [status.halfred.ai](https://status.halfred.ai) and contact support if the issue persists.

### Can I get notified about API issues?

Subscribe to status updates at [status.halfred.ai](https://status.halfred.ai) or join our Discord.

### How do I report a bug?

Email <support@halfred.ai> with error details and request IDs.

## Related Documentation

* [Authentication](https://docs.halfred.ai/01-getting-started/02-authentication.md)
* [API Reference](https://docs.halfred.ai/04-api-reference/01-endpoints.md)
* [Best Practices](https://docs.halfred.ai/05-advanced/01-best-practices.md)

## Support

Need help with errors?

* **Email**: <support@halfred.ai>
* **Discord**: [Join our community](https://discord.gg/wS2awX4EV7)
* **Status**: [status.halfred.ai](https://status.halfred.ai)
