Errors

The problem details format and every error type the API returns.

Every error is a problem details document (RFC 9457), served as application/problem+json with Cache-Control: no-store.

{
  "type": "https://docs.pinakelai.com/errors/query-too-broad",
  "title": "Query too broad",
  "status": 422,
  "detail": "mark_text_phrase matches more than 100,000 records. Narrow the search.",
  "request_id": "req_01M7Q3ZV8X1B5C9D2F6G4H8J3K"
}

Member	Type	Meaning
type	string	A URL identifying the error type. Stable: branch on it. It opens the type’s page in these docs.
title	string	A short summary of the type, for people. Can be reworded.
status	integer	The HTTP status code.
detail	string	What went wrong with this request, for people. Can be reworded.
request_id	string	Equals the X-Request-Id header. Quote it to support.
errors	array	invalid-request only: every problem found in the request.
violated_policies	array of strings	429 only: the policies that refused the call, minute, month or concurrency.

New members can be added to problem documents; ignore members you do not know.

​

Error types

Status	Type	Title	Retry
400	invalid-request	Invalid request	No: fix the request
400	invalid-cursor	Invalid cursor	No: start again
400	cursor-mismatch	Cursor does not match the request	No: resend the original filters
401	unauthenticated	Authentication required	No: fix the credential
401	key-revoked	API key revoked	No: use a current key
403	product-not-enabled	Product not enabled for this key	No: ask for the product
404	not-found	Not found	No: an answer
404	unknown-endpoint	Unknown endpoint	No: fix the path
405	method-not-allowed	Method not allowed	No: fix the method
410	removed	Removed	No: move to /v1
413	payload-too-large	Payload too large	No: split the batch
415	unsupported-media-type	Unsupported media type	No: send JSON
422	query-too-broad	Query too broad	No: narrow the query
422	query-timeout	Query timed out	No: narrow the query
429	rate-limited	Rate limit exceeded	Yes, after Retry-After
429	quota-exceeded	Monthly quota exceeded	After the quota resets
500	internal-error	Internal error	Yes, with backoff
503	unavailable	Service unavailable	Yes, after Retry-After
503	jurisdiction-unavailable	Jurisdiction unavailable	Yes, after Retry-After (at least 900 s)
503	search-index-unavailable	Search index unavailable	Yes, later

The API never returns 504. New types can be added in v1; treat an unknown type by its status code.

​

Validation errors

invalid-request lists every problem with the request in errors. Each entry has a code, a detail, and either parameter or pointer:

{
  "type": "https://docs.pinakelai.com/errors/invalid-request",
  "title": "Invalid request",
  "status": 400,
  "detail": "The request has invalid parameters; see errors.",
  "request_id": "req_01M7Q3ZW9Y2C6D1F3G7H5J9K4M",
  "errors": [
    { "code": "invalid-body", "detail": "Not a valid trademark id.", "pointer": "/ids/2" },
    { "code": "invalid-body", "detail": "At most 25 ids with include=source_record.", "pointer": "/ids" }
  ]
}

code	Cause
unknown-parameter	A parameter that does not exist; the detail suggests the closest valid one
reserved-parameter	q, which is reserved; use mark_text_phrase
missing-filter	A search with no filter
invalid-parameter	A value that is malformed, out of range, or not allowed in this combination
query-too-long	A cursor longer than 6,000 characters, or a query string longer than 32 KB
invalid-body	A batch body that is not valid JSON, has unknown members, or holds bad or too many ids
not-yet-available	A parameter reserved for a later version, such as goods_services_phrase

parameter names a query parameter. pointer is a JSON Pointer into the batch request body. New codes can be added.

​

Headers on errors

Header	On
X-Request-Id	Every error
WWW-Authenticate	401 and 403. See Authentication.
Retry-After	429 and 503, in seconds
RateLimit, RateLimit-Policy	Errors on authenticated requests

​

Errors from the edge

Requests stopped before they reach the API, by Pinakel’s edge protection or by the network, can get a status without a problem document: typically a 429 or 403 with an HTML or empty body, or a 502. Handle them by status code; Handling errors shows how.