---
title: Errors
description: The error shape every endpoint returns, and what each error type means.
sidebar:
  label: Errors
  order: 4
---

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

```json
{
  "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`](/docs/reference/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.