Error Handling

Error Response Format

All errors follow this structure:

{
  "data": null,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  },
  "meta": {
    "request_id": "d6a8f6f2-3b5a-4f0a-81ab-1b4a4c9dd5ea",
    "timestamp": "2026-03-08T21:56:33.877635522Z",
    "version": "1.0.0"
  }
}

Error Codes

Code	HTTP Status	Description
`MISSING_API_KEY`	401	API key header missing
`INVALID_API_KEY`	401	Invalid or revoked API key
`API_KEY_DISABLED`	403	API key disabled
`FORBIDDEN`	403	Invalid API key type for this endpoint, API access not enabled for your team, or access denied
`INVALID_INPUT`	400	Request body is missing or malformed
`PAYLOAD_TOO_LARGE`	413	Request body exceeds the 1MB size cap
`MINUTE_LIMIT_EXCEEDED`	429	Per-minute rate limit exceeded (includes `Retry-After: 60` header)
`DAILY_LIMIT_EXCEEDED`	429	Daily request limit exceeded (includes `Retry-After: 3600` header)
`MONTHLY_LIMIT_EXCEEDED`	429	Monthly request limit exceeded (includes `Retry-After: 3600` header)
`IP_RATE_LIMITED`	429	Too many failed auth attempts from this IP
`INTERNAL_ERROR`	500	Server error
`REDIS_UNAVAILABLE`	503	Rate limiter temporarily unavailable (free tier only — paid users are unaffected). Includes `Retry-After: 30` header.

Common Errors

Missing API Key (401)

{
  "data": null,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required"
  },
  "meta": { "request_id": "...", "timestamp": "...", "version": "1.0.0" }
}

Solution: Add your API key to the x-api-key header.

Invalid API Key (401)

{
  "data": null,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  },
  "meta": { "request_id": "...", "timestamp": "...", "version": "1.0.0" }
}

Solution: Check that your API key is correct and not revoked.

Rate Limit Exceeded (429)

{
  "data": null,
  "error": {
    "code": "MINUTE_LIMIT_EXCEEDED",
    "message": "Per-minute rate limit exceeded. Retry after 60 seconds."
  },
  "meta": { "request_id": "...", "timestamp": "...", "version": "1.0.0" }
}

Solution: For all rate limit errors, check the Retry-After header and wait the indicated number of seconds before retrying. Alternatively, upgrade your plan to increase your limits.

Handling Errors in Code

try {
  const response = await client.analyzeMessage("...");

  if (response.error) {
    console.error(`Error: ${response.error.code}`);
    console.error(`Message: ${response.error.message}`);
    // Handle specific error codes
    if (response.error.code === 'MINUTE_LIMIT_EXCEEDED') {
      // Check Retry-After header and wait
    } else if (response.error.code === 'DAILY_LIMIT_EXCEEDED') {
      // Wait for daily reset
    }
  }
} catch (error) {
  console.error('Network error:', error);
}

try:
    response = client.analyze_message(message="...")

    if response.error:
        print(f"Error: {response.error.code}")
        print(f"Message: {response.error.message}")
        # Handle specific error codes
        if response.error.code == 'MINUTE_LIMIT_EXCEEDED':
            # Check Retry-After header and wait
            pass
        elif response.error.code == 'DAILY_LIMIT_EXCEEDED':
            # Wait for daily reset
            pass
except Exception as e:
    print(f"Network error: {e}")

Request IDs

Every response includes a request_id in the meta object. Include this ID when contacting support for faster issue resolution.

Getting Started

Integrations

Configuration

Monetization

Analytics & Data

MCP Tools

Trust & Performance

Account

Troubleshooting

Error Response Format

Error Codes

Common Errors

Missing API Key (401)

Invalid API Key (401)

Rate Limit Exceeded (429)

Handling Errors in Code

Request IDs

​Error Response Format

​Error Codes

​Common Errors

​Missing API Key (401)

​Invalid API Key (401)

​Rate Limit Exceeded (429)

​Handling Errors in Code

​Request IDs

Error Response Format

Error Codes

Common Errors

Missing API Key (401)

Invalid API Key (401)

Rate Limit Exceeded (429)

Handling Errors in Code

Request IDs