Error Codes

Reference for all error codes returned by the Events API.

Error Response Format

All errors follow this structure:

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

HTTP Status Codes

Status	Meaning
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limited
500	Internal Server Error
503	Service Unavailable - Maintenance

Error Codes

INVALID_PARAMETER

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Invalid value for parameter 'types'",
    "details": {
      "parameter": "types",
      "value": "INVALID_TYPE",
      "allowed": ["FORM_4", "FILING_8K", "FILING_10K", "FILING_10Q", "NEWS"]
    }
  }
}

Cause: A query parameter has an invalid value. Fix: Check the allowed values in the API reference.

INVALID_DATE_RANGE

{
  "error": {
    "code": "INVALID_DATE_RANGE",
    "message": "End date must be after start date",
    "details": {
      "start": "2025-01-15T00:00:00Z",
      "end": "2025-01-01T00:00:00Z"
    }
  }
}

Cause: The end parameter is before start. Fix: Ensure end date is chronologically after start date.

UNAUTHORIZED

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key"
  }
}

Cause: Missing, invalid, or expired API key. Fix: Include a valid Authorization: Bearer <key> header.

RATE_LIMIT_EXCEEDED

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "details": {
      "limit": 100,
      "window": "1 minute",
      "retryAfter": 45
    }
  }
}

Cause: Too many requests in the time window. Fix: Wait retryAfter seconds before retrying. Implement exponential backoff.

CONNECTION_LIMIT_EXCEEDED

{
  "error": {
    "code": "CONNECTION_LIMIT_EXCEEDED",
    "message": "Maximum concurrent SSE connections exceeded",
    "details": {
      "limit": 5,
      "current": 5
    }
  }
}

Cause: Too many concurrent SSE connections from your IP. Fix: Close unused connections before opening new ones.

INTERNAL_ERROR

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred",
    "details": {
      "requestId": "req-abc123"
    }
  }
}

Cause: Server-side error. Fix: Retry with exponential backoff. Contact support if persistent, include requestId.

SERVICE_UNAVAILABLE

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable for maintenance",
    "details": {
      "estimatedDowntime": "15 minutes"
    }
  }
}

Cause: Planned maintenance or capacity issues. Fix: Wait and retry. Check status page for updates.

SSE Connection Errors

For SSE streams, errors appear as events:

event: error
data: {"error":{"code":"CONNECTION_LIMIT_EXCEEDED","message":"..."}}

Handle in your client:

source.addEventListener('error', (e) => {
  if (e.data) {
    const error = JSON.parse(e.data);
    console.error('Stream error:', error.error.code);
  }
});

Best Practices

1. Always check HTTP status before parsing response body
2. Log the requestId for internal errors to help debugging
3. Implement retry logic with exponential backoff
4. Monitor rate limit headers to avoid hitting limits
5. Handle all error codes gracefully in your application