PatentRef API error codes (X-Status-Reason-Code; the RFC 9457 problem type is https://patentref.io/docs/errors/) ERR_Q 400 Bad Request. The q, f, s or o parameter is invalid: malformed JSON in q, f, s or o; no q on a list endpoint other than the lookup endpoints (the cpc, uspc, ipc and wipo lists); more than one top-level key in q; an unknown field; a field outside the endpoint; a sort on a text field without a keyword form; q or s on the lapse group (it is returned with f only); 'offset' in o; a query over the cost cap (100 units, 64 criteria, depth 8); q over 16 KB (16,384 bytes) in a POST body. The cost cap also refuses _contains, a range or an empty _begins on a long-text field (claim_text, summary_text, description_text, draw_desc_text) without patent_id in the same _and: no index serves them, so they would read the whole table; use _text_any, _text_all or _text_phrase there. The X-Status-Reason header carries the upstream text. Two size limits answer before the API and carry no X-Status-Reason-Code: a request body over 64,000 bytes answers 413 with an empty body, and a GET whose request line (the method, the path with its query string and the protocol) is over 4,094 bytes answers 400 with an HTML page, so a large q goes in a POST body. ERR_KEY 403 Forbidden. No X-Api-Key header, or the key is unknown or revoked. Get a Free key at /api/v1/meta/signup/. A data endpoint answers the upstream body {"detail": "You do not have permission to perform this action."} with no X-Status-Reason-Code header; the code appears as that header only on the account endpoints, and in the problem details body. ERR_ES 500 Internal Server Error. The search backend raised an error or a timeout (20 s a statement, 30 s a request), or an operator was used on a field type that rejects it (prefix or wildcard on numeric, date and boolean fields). On /api/v1/structure/claims// also a patent whose claims are over that endpoint's work cap (1,000 claim rows, 1,000,000 characters, 5 s a read), and on /api/v1/structure/brief// and /api/v1/structure/counts//, which share it; no patent of the data in service is near it. ERR_NOT_IMPLEMENTED 501 Not Implemented. The endpoint's data set is not in this snapshot: pre-grant publications are deferred to a later build, the NBER routes are dead upstream, the long-text endpoints answer it only when no long-text file is in service (GET /api/v1/meta/health/ shows text_data_version), and any other endpoint answers it while the build in service does not carry its data set. GET /api/v1/meta/ lists the data sets the build lacks under deferred. The X-Status-Reason header names the data set and, where there is one, where the same facts are served (the classifications come with each patent on /api/v1/patent/). A 501 does not count toward the monthly allowance. ERR_AUTH 401 Unauthorized. The account endpoints need Authorization: Bearer ; the token is missing, expired or not from the PatentRef project. ERR_SIGNUP_LIMIT 429 Too Many Requests. More than the daily number of new accounts from one email domain; try after the Retry-After seconds. ERR_TERMS 403 Forbidden. POST /api/v1/meta/keys/ mints or rotates a key only once the PatentRef Terms of Service, Privacy Policy and Acceptable Use Policy are accepted (https://patentref.io/docs/legal/terms, /docs/legal/privacy, /docs/legal/acceptable-use). Read them, then send {"terms_version": ""} in the body; the body of the 403 names the current version and the links, and the box on the sign-up page sends it. An account that accepted the current version at sign-up or with its last key needs nothing more. Keys minted before the terms were asked keep working. THROTTLED 429 Too Many Requests. Over the per-minute allowance (45 for a Free key, a fixed UTC clock minute) or the monthly allowance (1,000). Retry-After says when the window resets; the body is DRF's 'Request was throttled. Expected available in N seconds.' What counts toward the month: keyed requests to data paths answered below 500 other than 403 and 429 (400 and 404 count); the /api/v1/meta/ endpoints never count. NOT_FOUND 404 Not Found. A detail route with a key that has no record ({"detail": "Not found."}), or a path that is not routed. On /api/v1/lapse/status// an unknown patent answers the same {"detail": "Not found."}, and a v that never existed answers {"error": true} with X-Status-Reason-Code NOT_FOUND. On /api/v1/structure/claims// (and on /api/v1/structure/brief// and /api/v1/structure/counts//) a patent the data in service does not have, and a patent it has without claim text in the long-text file (a grant after that file's last grant date), answer {"error": true} with X-Status-Reason-Code NOT_FOUND and the reason in X-Status-Reason. Those answers carry NOT_FOUND as a header; on the others it is the problem details code. The X-Status-Reason-Code header carries ERR_Q, ERR_ES and ERR_NOT_IMPLEMENTED on the data endpoints; NOT_FOUND on /api/v1/lapse/status/ for a v that never existed and on /api/v1/structure/claims/ for a patent without a claim tree, as on /api/v1/structure/brief/ and /api/v1/structure/counts/; ERR_KEY, ERR_AUTH, ERR_SIGNUP_LIMIT and ERR_TERMS on the account endpoints under /api/v1/meta/. A data endpoint's 403 and 429 and a detail route's 404 carry no code header, as upstream; the problem details body names them ERR_KEY, THROTTLED and NOT_FOUND. Send Accept: application/problem+json on any request to receive errors as problem details objects; the upstream body {"error": true} and the headers X-Status-Reason and X-Status-Reason-Code are the default. Full guide: https://patentref.io/llms-full.txt