Error Handling

Handle API errors gracefully with clear patterns and solutions.

Mind Reasoner API

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:

1{
2 "error": "Error Type",
3 "message": "Human-readable description of what went wrong",
4 "code": "MACHINE_READABLE_CODE",
5 "details": {
6 "field": "parameter_name",
7 "value": "invalid_value"
8 }
9}

HTTP Status Codes

4️⃣

Client Errors (4xx)

Your request has an issue. Check authentication, parameters, or permissions.

5️⃣

Server Errors (5xx)

Something went wrong on our end. Retry with exponential backoff.

2️⃣

Success (2xx)

Request succeeded. 200 (OK) or 201 (Created) indicate successful operations.


Common Errors

401 Unauthorized

Cause: Missing or invalid API key

Response:

1{
2 "error": "Unauthorized",
3 "message": "Invalid or missing API key",
4 "code": "AUTH_FAILED"
5}

Solutions:

  1. Verify API key is correct
  2. Check Authorization header format: Bearer YOUR_KEY
  3. Ensure there’s a space between “Bearer” and your key
  4. Confirm key hasn’t been revoked

Example Fix:

1// Wrong
2headers: { 'Authorization': 'BearerYOUR_KEY' }
3
4// Correct
5headers: { 'Authorization': 'Bearer YOUR_KEY' }

403 Forbidden

Cause: Valid key but insufficient permissions

Response:

1{
2 "error": "Forbidden",
3 "message": "Your account doesn't have access to this resource",
4 "code": "INSUFFICIENT_PERMISSIONS"
5}

Solutions:

  1. Check your subscription level
  2. Verify resource belongs to your account
  3. Ensure you have the required role
  4. Contact support if issue persists

Error Handling Patterns

Basic Try-Catch

1try {
2 const response = await axios.post(url, data, { headers });
3 return response.data;
4} catch (error) {
5 if (error.response) {
6 // API returned an error response
7 console.error('API Error:', error.response.data);
8 console.error('Status:', error.response.status);
9 } else if (error.request) {
10 // Request made but no response received
11 console.error('Network Error:', error.message);
12 } else {
13 // Error setting up the request
14 console.error('Error:', error.message);
15 }
16 throw error;
17}

Retry with Exponential Backoff

1async function makeRequestWithRetry(fn, options = {}) {
2 const {
3 maxRetries = 3,
4 initialDelay = 1000,
5 maxDelay = 32000,
6 retryableStatuses = [408, 429, 500, 502, 503, 504]
7 } = options;
8
9 for (let attempt = 0; attempt < maxRetries; attempt++) {
10 try {
11 return await fn();
12 } catch (error) {
13 const status = error.response?.status;
14 const isRetryable = retryableStatuses.includes(status);
15 const isLastAttempt = attempt === maxRetries - 1;
16
17 if (!isRetryable || isLastAttempt) {
18 throw error;
19 }
20
21 const delay = Math.min(
22 initialDelay * Math.pow(2, attempt),
23 maxDelay
24 );
25
26 console.log(`Retry attempt ${attempt + 1}/${maxRetries} after ${delay}ms`);
27 await new Promise(resolve => setTimeout(resolve, delay));
28 }
29 }
30}
31
32// Usage
33const result = await makeRequestWithRetry(async () => {
34 return await axios.post(url, data, { headers });
35});

Best Practices

🔄

Always Retry

  • Implement exponential backoff for 5xx errors
  • Respect retryAfter headers
  • Set reasonable retry limits (3-5 attempts)
  • Log retry attempts for debugging
📝

Log Everything

  • Log error responses with status codes
  • Include requestId for 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:

1

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.

2

Read Error Message

The message field provides human-readable context. The details field often contains specific parameter issues.

3

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:

  1. Check the docs: Search this documentation for your specific error code
  2. Review examples: Compare your code against working examples in Getting Started
  3. 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.