Errors & Limits

Understanding API errors, rate limits, and plan restrictions.

Error Response Format

All errors follow a consistent format:

{
  "statusCode": 400,
  "statusMessage": "Name is required",
  "message": "Name is required",
  "url": "/api/v1/sparks",
  "error": true
}

Always rely on statusCode for programmatic handling and statusMessage (or message) for the human-readable reason. The url and error fields are convenience metadata from the underlying framework.

HTTP Status Codes

2xx Success

4xx Client Errors

5xx Server Errors

Common Errors

400 Bad Request

Missing Required Field:

{
  "statusCode": 400,
  "statusMessage": "Name is required"
}

Invalid Input:

{
  "statusCode": 400,
  "statusMessage": "File too large: document.pdf (35.2MB). Maximum size is 30MB."
}

401 Unauthorized

Missing API Key:

{
  "statusCode": 401,
  "statusMessage": "Unauthorized"
}

Solution: Include the Authorization header:

-H "Authorization: Bearer minds_your_api_key"

403 Forbidden

Plan Limit Reached:

{
  "statusCode": 403,
  "statusMessage": "Free plan limit: maximum 3 minds. Upgrade your subscription to add more."
}

Access Denied:

{
  "statusCode": 403,
  "statusMessage": "Access denied"
}

404 Not Found

Resource Doesn't Exist:

{
  "statusCode": 404,
  "statusMessage": "Spark not found"
}

415 Unsupported Media Type

Wrong Content-Type:

{
  "statusCode": 415,
  "statusMessage": "Unsupported Content-Type. Use application/json for links or multipart/form-data for files"
}

Solution: Use the correct Content-Type header:

• application/json for JSON requests
• multipart/form-data for file uploads

429 Too Many Requests

Rate Limit Exceeded:

{
  "statusCode": 429,
  "statusMessage": "Too many requests. Please try again later."
}

Rate Limits

Note: The API does not currently enforce rate limits. However:

• Be respectful of server resources
• Avoid excessive parallel requests
• Implement reasonable delays between requests
• Excessive usage may result in throttling or account suspension

If rate limits are implemented in the future, you'll receive a 429 Too Many Requests error.

Plan Limits

Different plans have different resource limits.

Mind Limits

Error when limit reached:

{
  "statusCode": 403,
  "statusMessage": "Free plan limit: maximum 1 sparks. Upgrade your subscription to add more."
}

Knowledge Upload Limits

• File Size: Maximum 30MB per file (all plans)
• Storage: No explicit storage limits currently enforced

API Key Limits

• Maximum Keys: 10 per user (all plans)

Best Practices

Error Handling

Always handle errors:

try {
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
  });

  if (!response.ok) {
    const error = await response.json();
    console.error(`Error ${error.statusCode}: ${error.message}`);
    // Handle specific errors
    if (error.statusCode === 429) {
      // Implement retry logic
    }
  }

  const result = await response.json();
  return result;
} catch (error) {
  console.error('Network error:', error);
}

Retry Logic

Implement smart retries:

• Retry on 429 (rate limit) and 5xx errors
• Use exponential backoff
• Set maximum retry attempts
• Don't retry on 4xx errors (except 429)

Monitoring

Track your usage:

• Log rate limit headers
• Monitor error rates
• Set up alerts for recurring errors
• Track response times

Upgrade When Needed

Upgrade your plan if you:

• Hit rate limits frequently
• Need more minds
• Require larger file uploads
• Want priority support

View Plans

Getting Help

Check Status

Monitor our service status:

• Status page (coming soon)
• Follow @mindsai_co for updates

Contact Support

If you experience:

• Persistent 500 errors
• Incorrect rate limiting
• Unexpected behavior

Contact us:

• Feedback form
• Email: [email protected]

Review Documentation

• API Overview
• Authentication
• Sparks API
• Knowledge API
• Chat API

Status Codes Reference

Quick reference for all HTTP status codes:

2xx Success
├─ 200 OK
└─ 201 Created

4xx Client Error
├─ 400 Bad Request
├─ 401 Unauthorized
├─ 403 Forbidden
├─ 404 Not Found
├─ 415 Unsupported Media Type
└─ 429 Too Many Requests

5xx Server Error
├─ 500 Internal Server Error
└─ 503 Service Unavailable