- Error Response Format
- HTTP Status Codes
- Common Errors
- 401 Unauthorized
- 403 Forbidden
- 400 Bad Request
- 404 Not Found
- 429 Too Many Requests
- 500 Internal Server Error
- 503 Service Unavailable
- Error Handling Patterns
- Basic Try-Catch
- Retry with Exponential Backoff
- Best Practices
- Debugging Checklist
- Getting Help
- What’s Next?
Error Handling

Predictable Errors
Mind Reasoner API uses standard HTTP status codes and returns consistent JSON error responses. Every error includes actionable information to help you resolve issues quickly.
Error Response Format
All errors follow a consistent structure:
HTTP Status Codes
Client Errors (4xx)
Your request has an issue. Check authentication, parameters, or permissions.
Server Errors (5xx)
Something went wrong on our end. Retry with exponential backoff.
Success (2xx)
Request succeeded. 200 (OK) or 201 (Created) indicate successful operations.
Common Errors
Authentication
Validation
Not Found
Rate Limiting
Server Errors
401 Unauthorized
Cause: Missing or invalid API key
Response:
Solutions:
- Verify API key is correct
- Check Authorization header format:
Bearer YOUR_KEY - Ensure there’s a space between “Bearer” and your key
- Confirm key hasn’t been revoked
Example Fix:
403 Forbidden
Cause: Valid key but insufficient permissions
Response:
Solutions:
- Check your subscription level
- Verify resource belongs to your account
- Ensure you have the required role
- Contact support if issue persists
Error Handling Patterns
Basic Try-Catch
Retry with Exponential Backoff
Best Practices
Always Retry
- Implement exponential backoff for 5xx errors
- Respect
retryAfterheaders - Set reasonable retry limits (3-5 attempts)
- Log retry attempts for debugging
Log Everything
- Log error responses with status codes
- Include
requestIdfor support tickets - Track error patterns over time
- Monitor rate limit usage
User-Friendly Messages
- Don’t expose API errors directly to users
- Provide actionable error messages
- Offer alternative actions when possible
- Include support contact for persistent issues
Debugging Checklist
When encountering errors, work through this checklist:
Check Status Code
Identify whether it’s a client error (4xx) or server error (5xx). Client errors require changes to your request; server errors may be temporary.
Read Error Message
The message field provides human-readable context. The details field often contains specific parameter issues.
Review Documentation
Compare your request against the API Reference to ensure all required parameters are included and formatted correctly.
Getting Help
Support Resources
If you’re stuck:
- Check the docs: Search this documentation for your specific error code
- Review examples: Compare your code against working examples in Getting Started
- Contact support: Email support@mindreasoner.com with:
- Error message and status code
- Request ID (if provided)
- Code snippet (remove API keys!)
- What you’ve tried so far
What’s Next?
Start Building
Ready to implement error handling? Follow the Quick Start guide with confidence.
API Reference
See all possible responses for each endpoint in the API Reference documentation.
Authentication
Review authentication best practices in the Authentication guide.
