Errors

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.

Overview

Trademarks

Changes

Jurisdictions

Account

Error types

Validation errors

Headers on errors

Errors from the edge

​Error types

​Validation errors

​Headers on errors

​Errors from the edge

Error types

Validation errors

Headers on errors

Errors from the edge