Errors

The error shape every endpoint returns, and what each error type means.

Every endpoint returns errors in the same shape, so you can write one error handler for the whole API:

{
  "error": {
    "type": "invalid_request",
    "message": "Unknown event_type \"earnings\". Use one of the slugs below.",
    "valid_event_types": [
      { "event_type": "Corporate Earnings", "slug": "corporate-earnings" }
    ]
  }
}

type and message are always present. Some errors include extra fields to help you recover — e.g. invalid_request on an unknown event_type also returns valid_event_types, the exact list of slugs /v1/events would give you.

Error types

Type	HTTP status	When it happens
`unauthorized`	401	The `Authorization` header is missing, malformed, or the key is invalid/revoked.
`invalid_request`	400	A query parameter failed validation — e.g. an `event_type` that doesn’t match any known category.
`server_error`	502	An upstream failure while fetching data. Safe to retry with backoff.

Handling errors

Treat 401 as a signal to check your key — is it present, correctly formatted (Bearer <key>), and not revoked?
Treat 400 as a client-side bug to fix, not something to retry as-is — read message (and valid_event_types when present) to correct the request.
Treat 502 as transient — retry with backoff. If it persists, it’s worth checking status or reaching out.