Copy page

Usage, Limits & Reliability

Errors and Status Codes

The IntelCenter API uses standard HTTP status codes to indicate the success or failure of a request.

---

Overview

Status Code	Meaning
200 OK	Request was successful
400 Bad Request	Invalid request parameters
401 Unauthorized	Missing or invalid API key
403 Forbidden	Access to dataset or feature is not permitted
404 Not Found	Resource not found
429 Too Many Requests	Rate limit or quota exceeded
500 Internal Server Error	Server-side error

---

Error Response Format

When an error occurs, the API may return a JSON response with additional details:

Code
{
  "error": "error_code",
  "message": "Human-readable description of the error"
}

Some responses may include additional fields depending on the error type (e.g., limits, tier, or context).

---

Common Errors

400 Bad Request

The request was invalid or contained unsupported parameters.

Possible causes:

• Invalid query parameter values
• Incorrect parameter format (e.g., invalid date)
• Unsupported parameter names

Example:

Code
{
  "error": "bad_request",
  "message": "Invalid query parameter format"
}

---

401 Unauthorized

Authentication failed.

Possible causes:

• Missing Authorization header
• Invalid API key
• Expired or revoked API key

Fix: Ensure your request includes:

Code
Authorization: Bearer YOUR_API_KEY

---

403 Forbidden

The request was valid, but your API key does not have permission to access the requested dataset or feature.

Possible causes:

• API key does not include the requested dataset
• Entity-level restrictions block access
• Feature (e.g., Natural Language or Domain GenAI) not enabled for your key

Example:

Code
{
  "error": "FORBIDDEN",
  "message": "You do not have access to this dataset or feature."
}

---

404 Not Found

The requested resource could not be found.

Possible causes:

• Invalid UUID
• Incorrect endpoint path

Example:

Code
{
  "error": "not_found",
  "message": "Record not found"
}

---

429 Too Many Requests

You have exceeded a rate limit or quota.

This may be triggered by:

• Per-minute rate limits (search or detail endpoints)
• Domain GenAI limits (per-minute, hourly, or daily)
• Daily or monthly request quotas

Example:

Code
{
  "error": "quota_exceeded",
  "message": "This API key exceeded a usage or rate limit and the request was blocked.",
  "tier": "trial",
  "rate_limit": "domain-genai",
  "limits": {
    "daily_requests": 100,
    "monthly_requests": 1000
  },
  "action": "Wait for your quota to reset or contact IntelCenter if you need a higher usage allowance."
}

Recommended action:

• Reduce request frequency
• Implement retry logic with backoff
• Monitor usage against your plan limits

---

500 Internal Server Error

An unexpected error occurred on the server.

Possible causes:

• Temporary service issue
• Internal processing error

Recommended action:

• Retry the request
• Contact support if the issue persists

---

MCP Error Behavior

When using MCP endpoints:

• Errors still follow standard HTTP status codes
• Tool calls may return structured error responses
• Access restrictions apply per tool based on your API key
• Some invalid queries may return partial or empty results instead of hard errors

---

Troubleshooting Checklist

If your request is failing:

1. Verify the endpoint URL is correct
2. Confirm your API key is valid and included
3. Check query parameter names and formats
4. Ensure UUIDs are valid when requesting single records
5. Confirm your key has access to the dataset or feature
6. Review rate limits if receiving 429 errors

---

Best Practices

• Always handle non-200 responses in your application
• Implement retry logic for 429 and 500 errors
• Log error responses for debugging
• Validate inputs before sending requests
• Monitor usage to avoid hitting limits unexpectedly

---

Support

If you continue to experience issues:

[email protected]