Skip to main content

​
Error Codes

This page documents all error codes returned by the DocBit AI API and how to handle them.

​
Error Response Format

All errors follow this format: 
{
  "error": "Human-readable error message"
}

​
HTTP Status Codes

​
400 Bad Request

The request was malformed or missing required data.
Error MessageCauseSolution
Missing required header: X-External-Org-IdHeader not providedAdd the header to your request
Missing required header: X-External-User-IdHeader not providedAdd the header to your request
Missing required header: X-External-RolesHeader not providedAdd the header to your request
At least one role is requiredEmpty roles arrayProvide at least one role
Invalid JSON in request bodyMalformed JSONCheck your JSON syntax
Message is requiredEmpty or missing messageProvide a message in chat requests

​
401 Unauthorized

Authentication failed.
Error MessageCauseSolution
Invalid API key formatKey doesn’t start with correct prefixCheck key format
Invalid API keyKey not foundVerify your API key
API key is inactiveKey was deactivatedContact support for new key
API key has expiredKey past expiry dateContact support for new key

​
404 Not Found

The requested resource doesn’t exist.
Error MessageCauseSolution
Conversation not foundInvalid conversation IDCheck the ID or start new conversation
Document not foundInvalid document IDVerify document exists

​
413 Payload Too Large

The request body exceeds size limits.
Error MessageCauseSolution
Request entity too largeFile too bigReduce file size (max 100MB)

​
429 Too Many Requests

Rate limit exceeded.
Error MessageCauseSolution
Rate limit exceededToo many requestsWait and retry with backoff

​
500 Internal Server Error

Something went wrong on our end.
Error MessageCauseSolution
Internal server errorServer issueRetry, contact support if persists

​
Handling Errors

​
JavaScript

try {
  const response = await DocBit AIClient.post('/api/ai/chat', data, config);
  return response.data;
} catch (error) {
  if (error.response) {
    const { status, data } = error.response;
    
    switch (status) {
      case 400:
        console.error('Bad request:', data.error);
        break;
      case 401:
        console.error('Auth failed:', data.error);
        // Refresh API key or prompt user
        break;
      case 429:
        // Implement exponential backoff
        await sleep(Math.pow(2, retryCount) * 1000);
        return retry();
      default:
        console.error('API error:', status, data.error);
    }
  }
  throw error;
}

​
Python

try:
    response = client.chat(org_id, user_id, roles, message)
except requests.HTTPError as e:
    status = e.response.status_code
    error = e.response.json().get('error', 'Unknown error')
    
    if status == 400:
        raise ValueError(f'Bad request: {error}')
    elif status == 401:
        raise AuthenticationError(f'Auth failed: {error}')
    elif status == 429:
        time.sleep(2 ** retry_count)
        return retry()
    else:
        raise APIError(f'API error {status}: {error}')

​
Best Practices

Never assume API calls succeed. Always handle error responses.
Use exponential backoff for rate limits and transient errors.
Map API errors to user-friendly messages in your application.
Log error details server-side for troubleshooting.