Documentation Index
Fetch the complete documentation index at: https://docs.modelhunter.ai/llms.txt
Use this file to discover all available pages before exploring further.
All errors follow a consistent JSON structure:
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"details": {
"field": "prompt",
"reason": "Required field is missing"
}
}
}
HTTP Status Codes
| Status | Meaning | When |
|---|
400 | Bad Request | Invalid parameters |
401 | Unauthorized | Missing or invalid API key |
402 | Payment Required | Insufficient balance |
403 | Forbidden | Key lacks permissions |
404 | Not Found | Resource does not exist |
409 | Conflict | Resource state conflict |
422 | Unprocessable Entity | Business logic error |
429 | Too Many Requests | Rate limit exceeded |
500 | Internal Server Error | Unexpected server error |
502 | Bad Gateway | Provider returned an error |
503 | Service Unavailable | Provider temporarily down |
Error Codes
Authentication Errors (401)
| Code | Description |
|---|
AUTH_REQUIRED | No Authorization header provided |
AUTH_INVALID_TOKEN | API key is malformed or does not exist |
AUTH_TOKEN_EXPIRED | API key has passed its expiry date |
Permission Errors (403)
| Code | Description |
|---|
FORBIDDEN | Action not allowed |
KEY_PERMISSION_DENIED | API key lacks required provider/type permission |
KEY_EXPIRED | API key has expired |
KEY_REVOKED | API key has been deleted |
Resource Errors (404)
| Code | Description |
|---|
NOT_FOUND | Generic resource not found |
MODEL_NOT_FOUND | Requested model does not exist |
TASK_NOT_FOUND | Task ID does not exist |
PROVIDER_NOT_FOUND | Provider does not exist |
Validation Errors (400/422)
| Code | Description |
|---|
VALIDATION_ERROR | Request body failed validation |
INVALID_PARAMETER | A parameter value is out of range or wrong type |
MISSING_PARAMETER | A required parameter is missing |
Payment Errors (402)
| Code | Description |
|---|
INSUFFICIENT_BALANCE | Account balance too low for this request |
PAYMENT_REQUIRED | No payment method on file |
PAYMENT_FAILED | Charge attempt failed |
Business Logic Errors (422)
| Code | Description |
|---|
QUOTA_EXCEEDED | Monthly quota for this API key reached |
FILE_TOO_LARGE | Uploaded file exceeds size limit |
UNSUPPORTED_FORMAT | File format not supported |
Rate Limit Errors (429)
| Code | Description |
|---|
RATE_LIMIT_EXCEEDED | Too many requests — slow down |
Conflict Errors (409)
| Code | Description |
|---|
TASK_NOT_RETRYABLE | Only failed tasks can be retried |
Provider Errors (502)
| Code | Description |
|---|
PROVIDER_ERROR | Upstream provider returned an error |
PROVIDER_UNAVAILABLE | Provider is temporarily offline |
PROVIDER_TIMEOUT | Provider did not respond in time |
PROVIDER_RATE_LIMITED | Provider’s own rate limit hit |
Internal Errors (500)
| Code | Description |
|---|
INTERNAL_ERROR | Unexpected server error |
Retry Strategy
Retryable vs Non-Retryable
| Retryable | Non-Retryable |
|---|
429 Rate limited | 400 Validation error |
500 Internal error | 401 Authentication error |
502 Provider error | 402 Payment error |
503 Unavailable | 403 Permission error |
PROVIDER_TIMEOUT | 404 Not found |
PROVIDER_RATE_LIMITED | 409 Conflict |
Exponential Backoff
For retryable errors, use exponential backoff:
async function requestWithRetry(fn, maxRetries = 3) {
for (let attempt = 0; attempt <= maxRetries; attempt++) {
try {
return await fn();
} catch (error) {
if (attempt === maxRetries || !isRetryable(error.status)) {
throw error;
}
const delay = Math.min(1000 * Math.pow(2, attempt), 30000);
await new Promise((resolve) => setTimeout(resolve, delay));
}
}
}
function isRetryable(status) {
return [429, 500, 502, 503].includes(status);
}
Rate Limit Handling
When you receive a 429, check the X-RateLimit-Reset header for when you can retry:
if (response.status === 429) {
const resetTimestamp = response.headers.get("X-RateLimit-Reset");
const waitMs = parseInt(resetTimestamp, 10) * 1000 - Date.now();
await new Promise((resolve) => setTimeout(resolve, Math.max(waitMs, 1000)));
}
