# Errors

Errors are RFC 9457 problem bodies, served as `application/problem+json`, with the appropriate HTTP status. A problem body always has a stable, machine-readable `code` and the `request_id` of the request. The one exception is the `503` of `GET /v3/health` ; it carries the same health body as a `200`.

## Errors (problem bodies):

| Field | Type | Required | Description |
|---|---|---|---|
| `code` | string | yes |   |
| `detail` | string | yes |   |
| `length` | integer | no | Search query errors: length in characters of the offending part of q. |
| `parameter` | string | no | The offending parameter, for 400 responses. |
| `position` | integer | no | Search query errors: character offset in q. |
| `request_id` | string | yes |   |
| `status` | integer | yes |   |
| `title` | string | yes |   |
| `type` | string (URI) | yes |   |

The shape of a 400 for a misspelled parameter. The dots stand for text the API writes; match on `code`; `title` and `detail` are for people and may change.

```json
{
  "type": "…",
  "title": "…",
  "status": 400,
  "detail": "…",
  "code": "unknown_parameter",
  "parameter": "fromdate",
  "request_id": "…"
}
```

## Codes

| Code | Status | Meaning |
|---|---|---|
| `invalid_parameter` | 400 | A parameter has a value the API cannot accept. `parameter` names it. |
| `unknown_parameter` | 400 | The request has a query parameter the route does not define. `parameter` names it. |
| `unauthorized` | 401 | The API key is missing, unknown or not active. |
| `invalid_token` | 401 | The bearer token is not valid: expired, revoked, badly signed, or issued for another resource. |
| `forbidden` | 403 | The token's scope does not cover this route. |
| `not_found` | 404 | The route or the thing asked for does not exist. |
| `gone` | 410 | No route answers it. |
| `method_not_allowed` | 405 | The route does not take this method. The routes that read take `GET`, `HEAD` and `OPTIONS`; the webhook routes name theirs in the reference. |
| `rate_limited` | 429 | The organization's request rate is exceeded. Wait for `Retry-After`, then send the request again (see [Rate limits and quotas](https://www.secblast.com/docs/rate-limits)). |
| `timeout` | 504 | The request exceeded its time limit. Narrow the query (a smaller window, a `cik`) and try again. |
| `internal` | 500 | An error inside the API. Retrying may help; if it persists, send the `request_id` to support. |
| `db_unavailable` | 503 | The database is temporarily unavailable. Retry after the `Retry-After` delay. |
| `range_not_satisfiable` | 416 | The `Range` header asks for bytes the document does not have. |
| `request_too_large` | 413 or 431 | The request body or its headers are too large. |
| `warming_up` | 503 | The answer is computed in the background, and the first computation since the API started has not finished. Retry after the `Retry-After` delay. |
| `invalid_query` | 400 | The search query `q` cannot be read. `position` and `length` point at the part of `q`. |
| `query_too_complex` | 400 | The search query has too many terms or operators. `position` and `length` point at the part of `q`. |
| `prefix_too_broad` | 400 | A prefix term (`word*`) matches too many words. `position` and `length` point at it. |
| `negative_only_query` | 400 | The search query only excludes terms; it needs at least one term to match. |
| `unsupported_operator` | 400 | The search query uses an operator the search does not support. `position` and `length` point at it. |
| `invalid_cursor` | 400 | The search cursor is not valid for this query. |
| `search_timeout` | 503 | The search query ran out of time. A narrower query or date range answers faster. |
| `search_busy` | 503 | Full-text search has a full queue. Repeat the request after `Retry-After`. |
| `search_unavailable` | 503 | Full-text search cannot be reached now. |
| `ticker_resolution_unavailable` | 503 | Tickers cannot be resolved to companies now, so a search by ticker cannot run. |
| `no_text` | 404 | The filing has no text for the item or section asked for. |
| `not_covered` | 404 | The filing's form is not covered by this route's dataset. `routes` names the routes that cover it. |
| `conversion_timeout` | 503 | Converting the document to text took longer than the request allows. It goes on; repeat the request after `Retry-After`. |
| `document_too_large` | 422 | The document is larger than the server converts to text. `document` links the filed bytes. |
| `unsupported_media_type` | 415 | A request body that is not `application/json`. |
| `invalid_body` | 400 | The request body is not one JSON object, or a change names nothing to change. |
| `callbacks_unavailable` | 503 | The webhook routes cannot be served by this server just now. Some of these answers carry `Retry-After`. |
| `plan_required` | 403 | The organization's plan does not include the [filing stream](https://www.secblast.com/docs/stream), or [webhooks](https://www.secblast.com/docs/webhooks), or this kind of subscription. |
| `limit_reached` | 409 | The plan's limit is reached; `kind` says which (endpoints, filter or firehose subscriptions, or manual retries of a delivery), with `limit` and `used`. |
| `conflict` | 409 | The endpoint changed while the request was being checked. Send it again. |
| `quota_exceeded` | 429 | The month's included data transfer is used up and the organization has no prepaid credit. The body says when the allowance resets (see [Rate limits and quotas](https://www.secblast.com/docs/rate-limits)). |
| `blocked` | 403 | The organization of the key or token is suspended. |
| `invalid_state` | 409 | The delivery cannot be retried: it is not failed, it was billed, or it is a test send or a verification. |
| `replay_running` | 409 | A replay of this endpoint started a short time ago. Wait for `Retry-After`. |
| `test_running` | 409 | Another test send of the organization has not answered yet. |
| `endpoint_unverified` | 409 | The endpoint has not answered its challenge yet; see [Webhooks](https://www.secblast.com/docs/webhooks). |
| `endpoint_disabled` | 409 | The endpoint is inactive or disabled. |

A subscription whose query has `q`, `doctypes`, `primary_only=true` or `entityName` gets `400` `invalid_parameter` naming that parameter. The webhook routes are described in [Webhooks](https://www.secblast.com/docs/webhooks).

## Handling errors

- **Branch on `code`**, not on the wording of `title` or `detail`.
- **4xx: fix the request.** Retrying the same request gives the same answer. A 400 names the `parameter` at fault.
- **503 and 504: retry.** A 503 carries `Retry-After`; wait that long, then send the same request again. Back off further if it repeats.
- **`request_id`** is also in the `X-Request-Id` response header. Support can find a request by it.
- **An error that is not a problem body** (a plain 429, 502 or 503 page) comes from the proxy in front of the API, not from the API itself: during a restart, or when one address sends requests faster than the proxy allows. Treat it as retryable, with a pause.

## Statuses that are not errors

- `206` is the answer to a `Range` request for part of a document.
- `304` is the answer when `If-None-Match` matches the document's `ETag`: your copy is current.
