> ## Documentation Index
> Fetch the complete documentation index at: https://docs.canary.effectiveai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Read error responses, branch on stable codes, and decide when to retry.

Every V2 error returns JSON with an HTTP status, a stable `code`, and a human-readable `error`:

```json theme={null}
{
  "code": "invalid_request",
  "error": "Invalid request",
  "details": [
    {
      "location": "query",
      "path": ["limit"],
      "code": "invalid_value",
      "message": "Must be at least 1."
    }
  ],
  "requestId": "1791481731950-0"
}
```

| Field | Meaning |
| - | - |
| `code` | Stable machine-readable code. Branch on this and the HTTP status. |
| `error` | Short description for people. Don't parse it; the wording can change. |
| `details` | Only on `invalid_request` and `invalid_cursor`: up to 20 invalid inputs. May omit some fields. |
| `requestId` | Identifies this HTTP attempt. Include it when you contact support. It isn't an idempotency key. |

Each `details` entry has a `location` (`path`, `query`, `header`, or `body`), a `path` to the
input, a `code` (`required`, `invalid_type`, `invalid_value`, or `unknown_field`), and a `message`.
For an unknown field, `path` may only point to the containing object (`[]`).

New codes can be added. If you don't recognize a `code`, handle the response by its HTTP status.

## Error codes

| Status | Code | Meaning | What to do |
| - | - | - | - |
| 400 | `invalid_request` | A field name, type, enum value, or limit is wrong. | Fix the input named in `details`. Don't drop a filter to make it pass. |
| 400 | `invalid_cursor` | The cursor expired, or the query changed since it was issued. | Restart the query without a cursor. |
| 400 | `invalid_id` | A carrier, group, MGA, or product ID is malformed or fails its checksum. | Check for a typo, or use an ID the API returned. |
| 400 | `invalid_upload_content` | Uploaded bytes don't match `sizeBytes`, or the PDF isn't valid. | Correct the file or its size and [start a new upload](/guides/managed-filings/manage-documents). |
| 401 | `unauthenticated` | The key is missing, invalid, expired, revoked, or not a supported type. | Check the key and host, then call `/users/me`. Don't retry with the same key. |
| 403 | `forbidden` | The key is valid but can't perform this operation. | Check that your user has access to the resource, and that it's an ordinary user key. |
| 403 | `download_restricted` | The file is part of a licensed dataset. Its original and text can't be exported. | Use the filing's metadata, or ask support about access. |
| 404 | `not_found` | The resource doesn't exist, or you can't access it. | Check the ID. A resource you can't access also returns `404`. |
| 409 | `conflict` | The resource's current state prevents this change. | Read the resource again and decide whether to retry. See the guide for that operation. |
| 409 | `text_unavailable` | The file has no extracted text. | [Download the original](/guides/read-filing-documents) instead. |
| 409 | `inventory_limit_exceeded` | The filing has too many files to list. | Treat the file list as incomplete. |
| 409 | `version_unavailable` | That exact file version can't be downloaded. | Don't retry the same request. Report the `requestId` if you need that version. |
| 413 | `request_too_large` | The request body is too large. | Send a smaller body. |
| 415 | `unsupported_media_type` | The body isn't JSON. | Send `Content-Type: application/json`. |
| 429 | `rate_limited` | You sent too many requests. | Wait for `Retry-After` seconds, then retry. |
| 500 | `internal_error` | Something failed on Effective's side. | Save the `requestId` and report it. Don't assume a write failed. |
| 503 | `temporarily_unavailable` | A dependency is briefly unavailable. | Wait for `Retry-After` seconds, then retry a limited number of times. |

## Retry safely

* **Reads** are safe to retry. Retry `429` and `503` after `Retry-After`, with a limit on attempts.
* **Writes** don't support idempotency keys. After a timeout or `500`, check whether the write was
  saved before you send it again. See
  [Retry reads and reconcile writes](/guides/managed-filings#retry-reads-and-reconcile-writes).
* **Don't retry** `400`, `401`, `403`, or `404` unchanged; the same request fails the same way.

For pagination errors, see [Pagination and recovery](/guides/pagination-and-recovery).

## Get help

Email [support@effectiveailabs.com](mailto:support@effectiveailabs.com) with the `requestId`, the
time of the request, the method and path, and the status and `code` you received. Never send your
API key, the `Authorization` header, or a signed download URL.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.