Error Handling

DeepTagger API uses standard HTTP status codes and returns JSON error objects.

HTTP Status Codes

Code	Meaning	Description
200	OK	Request successful
400	Bad Request	Invalid parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions
404	Not Found	Project not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error

Error Response Format

{
  "status": "error",
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

Common Errors

INVALID_API_KEY

{
  "status": "error",
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or missing API key"
  }
}

Solution: Check your x-api-key header.

PROJECT_NOT_FOUND

{
  "status": "error",
  "error": {
    "code": "PROJECT_NOT_FOUND",
    "message": "Project with ID fo_123 not found"
  }
}

Solution: Verify the fo_id parameter.

MISSING_FILE

{
  "status": "error",
  "error": {
    "code": "MISSING_FILE",
    "message": "Either 'file' or 'text' parameter is required"
  }
}

Solution: Include either file or text in your request.

RATE_LIMIT_EXCEEDED

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 60 seconds."
  }
}

Solution: Implement retry with exponential backoff.

Best Practices

1. Check HTTP status first
2. Parse error response for details
3. Implement retry logic for 429 and 5xx errors
4. Log errors for debugging
5. Show user-friendly messages to end users

Example Error Handling

Python

try:
    response = requests.post(url, headers=headers, data=data, files=files)
    response.raise_for_status()
    data = response.json()
except requests.exceptions.HTTPError as e:
    if e.response.status_code == 429:
        # Rate limit - retry after delay
        time.sleep(60)
    elif e.response.status_code >= 500:
        # Server error - retry
        pass
    else:
        # Client error - fix request
        print(e.response.json())

JavaScript

try {
  const response = await axios.post(url, formData, config);
  return response.data;
} catch (error) {
  if (error.response) {
    // Server responded with error
    console.error('API Error:', error.response.data.error);

    if (error.response.status === 429) {
      // Rate limit - retry
      await new Promise(resolve => setTimeout(resolve, 60000));
    }
  } else if (error.request) {
    // Network error
    console.error('Network error');
  }
}