Error Handling

Handle API errors gracefully with clear patterns and solutions.

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

Authentication

Validation

Not Found

Rate Limiting

Server 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:

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:

1 // Wrong
2 headers: { 'Authorization': 'BearerYOUR_KEY' }
3 
4 // Correct
5 headers: { '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:

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

1 try {
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

1 async 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
33 const 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:

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.

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

Authentication

Validation

Not Found

Rate Limiting

Server 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:

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:

1 // Wrong
2 headers: { 'Authorization': 'BearerYOUR_KEY' }
3 
4 // Correct
5 headers: { '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:

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

1 try {
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

1 async 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
33 const 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:

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.

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	}

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

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

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

1	try {
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	}

1	async 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
33	const result = await makeRequestWithRetry(async () => {
34	return await axios.post(url, data, { headers });
35	});