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:

{
  "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 and contact support if the issue persists.

Can I get notified about API issues?

Subscribe to status updates at status.halfred.ai or join our Discord.

How do I report a bug?

Email [email protected] with error details and request IDs.

Related Documentation

• Authentication

• API Reference

• Best Practices

Support

Need help with errors?

• Email: [email protected]

• Discord: Join our community

• Status: status.halfred.ai