Skip to main content
Every error from the API is a problem details document (RFC 9457) with the media type application/problem+json:
  • Branch on type. It is a stable URL, and it opens the page that documents the error. title and detail are for people and can be reworded at any time.
  • Log request_id. It equals the X-Request-Id header, and support can find the request with it.
  • invalid-request adds an errors array listing every problem in the request; 429 responses add violated_policies. See the errors reference for every type.

Fix, wait, or retry

The API never returns 504. A search that runs out of time is a 422 query-timeout; any other timeout is a 503 unavailable. A timeout somewhere between you and the API shows up as a network error or a 502; treat it like a 503.

Retrying safely

Every operation is read-only, including POST /v1/trademarks/batch, so any request can be retried without side effects. Retry only on 429, 500 and 503 (and network errors), respect Retry-After when present, and otherwise back off exponentially with jitter.
Retry-After is in seconds. For a register that is reloading it is at least 900 (15 minutes): rather than sleeping that long inside a request, record the failure and let your next scheduled run try again.

Errors without a problem body

Requests stopped by our edge protection, before they reach the API, can get a 429 or 403 without a JSON body and without RateLimit or Retry-After headers. Treat a 429 without a body like rate-limited and back off, starting at a few seconds.

Validation errors

A 400 invalid-request lists every problem at once, so you can fix them all in one pass:
Each entry has a code, a detail, and either parameter (a query parameter name) or pointer (a JSON Pointer into the batch request body, such as /ids/3). Searching lists the codes.