Error Handling

The Entity Detector API uses standard HTTP status codes and returns detailed error messages to help you diagnose issues.

Error Response Format

When an error occurs, the API returns a JSON object with the following structure:

json

{
  "error": "Bad Request",
  "message": "Text must be between 200 and 30000 characters",
  "code": "INVALID_TEXT_LENGTH",
  "details": {
    "minLength": 200,
    "maxLength": 30000,
    "actualLength": 50
  }
}

Error Fields

Field	Description
error	HTTP status text
message	Human-readable error description
code	Machine-readable error code
details	Additional context (optional)

HTTP Status Codes

Success (2xx)

Code	Meaning
200 OK	Request successful

Client Errors (4xx)

Code	Meaning	Action
400	Bad Request	Check request body and parameters
401	Unauthorized	Check API token
403	Forbidden	Token lacks required permissions
404	Not Found	Check endpoint URL
429	Too Many Requests	Wait and retry, or upgrade plan

Server Errors (5xx)

Code	Meaning	Action
500	Internal Server Error	Retry later, contact support if persists
502	Bad Gateway	Temporary issue, retry later
503	Service Unavailable	Service under maintenance

Error Codes Reference

Validation Errors

Code	Description	Solution
INVALID_TEXT_LENGTH	Text too short or too long	Ensure text is 200-30,000 chars
INVALID_LANGUAGE	Invalid language code	Use ISO 639-1 codes (en, es, etc.)
MISSING_TEXT	Text field is required	Include text in request body
INVALID_JSON	Malformed JSON in request	Validate JSON syntax

Authentication Errors

Code	Description	Solution
INVALID_TOKEN	Token is invalid or revoked	Generate a new token
MISSING_TOKEN	No Authorization header	Add Bearer token header
TOKEN_EXPIRED	Token has expired	Generate a new token

Rate Limit Errors

Code	Description	Solution
QUOTA_EXCEEDED	Daily quota exhausted	Wait for reset or upgrade plan

Error Handling Example

Here's a comprehensive example of handling different error types:

javascript

async function analyzeText(text) {
  const response = await fetch('https://api.entitydetector.com/v1/analyze', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.API_KEY}`
    },
    body: JSON.stringify({ text })
  });

  if (!response.ok) {
    const error = await response.json();

    switch (response.status) {
      case 400:
        console.error('Invalid request:', error.message);
        // Handle validation errors
        break;
      case 401:
        console.error('Authentication failed:', error.message);
        // Check API token
        break;
      case 429:
        console.error('Rate limited:', error.message);
        // Wait and retry
        const retryAfter = error.retryAfter || 60;
        await new Promise(r => setTimeout(r, retryAfter * 1000));
        return analyzeText(text); // Retry
      case 500:
        console.error('Server error:', error.message);
        // Log and alert, maybe retry
        break;
      default:
        console.error('Unknown error:', error);
    }

    throw new Error(error.message);
  }

  return response.json();
}

Troubleshooting

Common Issues

Getting 401 Unauthorized?

• Verify the Authorization header format: Bearer YOUR_TOKEN
• Check for typos in your token
• Ensure the token hasn't been revoked
• Make sure there's no extra whitespace around the token

Getting 400 Bad Request?

• Check that Content-Type: application/json is set
• Validate your JSON syntax
• Ensure text is between 200 and 30,000 characters
• Check for encoding issues with special characters

Getting 429 Too Many Requests?

• Check the retryAfter field in the error response
• Implement exponential backoff in your retry logic
• Consider upgrading your plan
• Cache responses to reduce API calls

Still Having Issues?

If you're experiencing errors that you can't resolve, please contact support with:

The full error response
Your request (with sensitive data redacted)
Timestamp of when the error occurred