Errors

Signa uses standard HTTP status codes. 2xx means success, 4xx means something is wrong with the request, and 5xx means something went wrong on our side. Error responses share one format:

{
  "error": {
    "type": "not_found",
    "title": "Resource not found",
    "status": 404,
    "detail": "Trademark tm_xxx does not exist.",
    "instance": "/v1/trademarks/tm_xxx",
    "suggestion": "Check the trademark ID. Use GET /v1/trademarks?q=... to find marks by text.",
    "retryable": false,
    "retry_after": null
  },
  "request_id": "req_abc123"
}

Field	Description
`type`	Stable error code. Branch on this, not on `title` or `detail`.
`title`	Short summary.
`status`	HTTP status code.
`detail`	What went wrong with this request.
`instance`	The request path.
`suggestion`	How to fix it.
`retryable`	Whether retrying the same request can succeed.
`retry_after`	Seconds to wait before retrying, or `null`.
`request_id`	Include this when you contact support.

Some errors add fields, such as merged_into on entity_merged or credit_balance on insufficient_credits.

Error catalog

Status	Type	Description
400	`validation_error`	A parameter or body field is missing or invalid. `errors[]` lists each problem. See request format.
400	`id_type_mismatch`	The ID has the wrong prefix for this endpoint, e.g. a `tm_` ID where an `own_` ID is expected.
400	`cursor_expired`	The cursor is empty, malformed, from another endpoint, or no longer valid. Restart from the first page.
400	`cursor_invalid`	The cursor no longer matches the request, because a filter or the sort changed, the search index was rebuilt, or the ranking changed (`search_meta.ranking_version`). Restart from the first page.
400	`cursor_window_exceeded`	The cursor points past the 10,000-row search window.
401	`unauthorized`	The API key is missing, invalid, expired or revoked.
403	`forbidden`	The API key lacks the scope this endpoint needs.
403	`plan_gated`	Your plan doesn’t include this feature.
403	`plan_limit_exceeded`	The request goes beyond your plan’s limit, such as log retention.
403	`plan_upgrade_required`	Buying extra credits isn’t available on your plan.
403	`edge_rejected`	Blocked by our security rules before reaching the API, including a `GET` query string over 2 KB. Send long lists, such as many `trademark_ids`, by `POST`.
404	`not_found`	The resource doesn’t exist.
409	`conflict`	The `Idempotency-Key` was already used for a different request.
409	`idempotency_processing`	A request with this `Idempotency-Key` is still running. Retry shortly.
409	`resource_quota_exceeded`	You’ve reached your plan’s limit on portfolios, managed marks or watches.
409	`external_ref_conflict`	The `external_ref` is already used by another trademark in this portfolio.
409	`portfolio_in_use`	Webhook endpoints still reference this portfolio.
410	`entity_merged`	The owner or entity was merged into another. Use the ID in `merged_into`.
410	`attestation_expired`	The attestation period is older than the 25-month retention window.
410	`replay_window_expired`	The `after` checkpoint is older than the 30-day retention window.
413	`payload_too_large`	The request body is over 8 KB. Trademark search (`POST /v1/trademarks`) and batch and compute endpoints, such as `POST /v1/trademarks/batch` and `POST /v1/deadlines/compute`, accept up to 64 KB; image search uploads accept up to 8 MB. Split larger batches.
422	`entity_too_large`	The entity, entity group or family graph is too large for this request. Query a member directly, or retry an `include_family=true` request with `include_family=false`.
422	`portfolio_too_large`	Deadline computation is limited to portfolios of 5,000 marks.
422	`batch_too_large`	The batch has more items than the endpoint accepts. `item_count_limit` gives the limit.
422	`attestation_period_open`	The attestation period is the current month. Pass `partial=true` for an interim artifact.
422	`capability_not_available`	Signa doesn’t serve this data for the requested office, for example proceedings for an office whose `capabilities.proceedings` is not `available`. Carries `capability`, `capability_state` and `office_code`. Not charged.
422	`attestation_unsupported_scope`	Signa doesn’t cover any office in the watch’s scope.
422	`period_before_watch`	The attestation period ended before the watch was created, so there is no monitoring to attest. Request the month the watch was created in, or a later one.
429	`rate_limited`	Too many requests. Wait `retry_after` seconds. See Rate limits.
429	`daily_credit_cap_exceeded`	You’ve reached your daily credit cap. It resets at UTC midnight.
429	`insufficient_credits`	Your credit balance is used up.
500	`internal_error`	Something went wrong on our side.
502	`upstream_error`	A backend service failed to respond.
503	`service_unavailable`	A backend service is temporarily down or overloaded, or a search timed out before it finished.
504	`timeout`	The request took too long. Retry, or narrow your filters.
504	`preview_timeout`	The watch preview was too heavy to run. Narrow the query.

Retrying

Retry only when retryable is true, with exponential backoff and after retry_after seconds when set. The TypeScript SDK does this for you. See Resilience for patterns. If a 5xx error persists, report it with Submit Feedback and include the request_id, or email support@signa.so.

Edge-generated errors

Some errors come from our CDN before the request reaches the API: edge_rejected, payload_too_large, some rate_limited, and 502 when the API is unreachable. They use the same format, but request_id is req_unknown. Quote the x-amz-cf-id response header to support instead. A few infrastructure errors return HTML instead of JSON: 414 for an overly long URL, and 400 or 494 for oversized request headers. Check the Content-Type header before parsing an error body.

Overview

Trademarks

Parties

Records

Intelligence

Filing & docketing

Monitoring

Analytics

Reference

Administration

SDK

Error catalog

Retrying

Edge-generated errors

​Error catalog

​Retrying

​Edge-generated errors

Error catalog

Retrying

Edge-generated errors