Errors

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

{
  "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.
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 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.
Don’t retry 400, 401, 403, or 404 unchanged; the same request fails the same way.

For pagination errors, see Pagination and recovery.

Get help

Email [email protected] 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.

Getting Started

Research guides

Filing workspace

Error codes

Retry safely

Get help

​Error codes

​Retry safely

​Get help

Error codes

Retry safely

Get help