Errors

Every Signa API error follows a consistent structure inspired by RFC 9457. Errors are wrapped under an "error" key with machine-readable fields for programmatic handling.

Error Response Structure

{
  "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	Type	Description
`type`	string	Snake_case error type slug (stable identifier for programmatic use, e.g. `not_found`, `validation_error`, `rate_limited`)
`title`	string	Human-readable error title
`status`	integer	HTTP status code
`detail`	string	Specific error description for this instance
`instance`	string	Request path that caused the error
`suggestion`	string	Actionable fix guidance
`retryable`	boolean	Whether the client should retry
`retry_after`	integer or null	Seconds to wait before retry
`request_id`	string	Unique request identifier for support (top-level, alongside `error`)

Error Catalog

Status	Type Slug	Retryable	Title	Example Message	Common Cause	Fix
400	`validation_error`	No	Validation failed	”Parameter ‘limit’ must be between 1 and 100.”	Invalid query parameter, missing required field, malformed JSON body	Check the parameter types and ranges. See the endpoint documentation for accepted values.
400	`id_type_mismatch`	No	ID type mismatch	”Expected an owner ID (own_*) but received tm_abc123.”	Using a trademark ID where an owner ID is expected (or vice versa)	Use the correct ID prefix for the endpoint. Owner endpoints expect `own_`, trademark endpoints expect `tm_`, etc.
400	`cursor_expired`	No	Cursor expired	”The pagination cursor has expired. Start a new query.”	The cursor is blank, malformed, tampered with, issued for a different endpoint, or was signed under a key that has since been rotated. Cursors carry no expiry clock, so this is not an age limit	Start a fresh pagination session from the first page. Cursors have no fixed lifetime, so handle this on any page rather than planning around a window.
400	`cursor_invalid`	No	Cursor query mismatch, or Cursor page size mismatch	”This cursor was generated for a different query, sort order, or filter set.”	A cursor was replayed against a request that changed one of the parameters that endpoint binds into its cursor. Trademark search binds `sort`, `limit`, filters and query text; the citations endpoints bind only the endpoint and the sort direction. Check the endpoint’s reference page for what its cursor binds	Restart pagination from the first page under the new parameters, or keep every parameter identical across pages. Branch on the `type` slug, never on `title`. Distinct from `cursor_expired`, which means the cursor is blank, stale, tampered with, or from another endpoint.
401	`unauthorized`	No	Authentication required	”Invalid API key.”	Missing `Authorization` header, invalid key format, expired key, revoked key	Check that you are sending `Authorization: Bearer sig_YOUR_KEY` with a valid key. Verify the key has not expired or been revoked.
403	`forbidden`	No	Insufficient scope	”API key does not have the ‘trademarks:read’ scope.”	The API key is valid but lacks the required scope for this endpoint	Create a new API key with the required scopes, or update the existing key’s scopes via `PATCH /v1/organization/api-keys/{id}`.
403	`plan_upgrade_required`	No	Plan upgrade required	”Portfolios is not available on your current plan. Upgrade to access this feature.”	The endpoint belongs to a feature that is not included in your current plan (e.g. portfolios, watches, alerts, events)	Upgrade your plan to gain access. Contact sales if you need this capability enabled. Not retryable: the response will not change without a plan change.
403	`edge_rejected`	No	Request rejected by edge	”Request rejected by edge security rules.”	The request matched an edge security rule before reaching the API (generated at the edge; `request_id` is `req_unknown`)	Check the request for patterns that resemble attacks (raw SQL fragments, script tags, path traversal). If a legitimate request is blocked, see Edge-generated errors below.
404	`not_found`	No	Resource not found	”Trademark tm_xxx does not exist.”	The ID does not exist, was deleted, or belongs to a different resource type	Verify the ID is correct. Use search to find the resource if you do not have the exact ID.
409	`conflict`	No	Conflict	”Idempotency-Key has been used with a different request target or body.”	Reusing an `Idempotency-Key` header against a different URL or with a different request body	Generate a new unique idempotency key for each distinct request. If retrying the same request, use the same key AND the same URL AND the same body.
409	`idempotency_processing`	Yes	Idempotency key in use	”A request with this idempotency key is currently being processed.”	A retry with the same `Idempotency-Key` landed while the original request was still in flight	Wait briefly for the original request to finish, then retry with the same key to receive its cached result.
409	`external_ref_conflict`	No	External reference conflict	”External reference “ACME-2024-001” is already bound to a different trademark in this portfolio.”	An `external_ref` supplied when adding trademarks to a portfolio is already bound to a different trademark there, or the trademark already carries a different reference (references are immutable once set)	Choose a different `external_ref`, or remove the trademark from the portfolio and add it again to rebind. The whole add batch is rolled back, so nothing was written.
410	`entity_merged`	No	Entity merged	”Owner own_old123 has been merged into own_abc123.”	The owner/attorney was deduplicated, or a resolved entity (`ent_*`) was fused into another. The old ID is permanently redirected.	Follow the `merged_into` field in the error response to the canonical entity. Update any cached references.
413	`payload_too_large`	No	Payload too large	”Request body exceeds the 8 KB limit for this endpoint.”	The request body exceeded a size limit. Bodies over 8 KB are rejected at the edge (`request_id` is `req_unknown`) on every endpoint except image upload (`POST /v1/trademarks/search/image`), which has its own larger API-enforced limit. 8 KB is the effective request body ceiling everywhere else.	Reduce the body size. For bulk lookups, use the batch endpoints within their documented limits.
422	`entity_too_large`	No	Entity too large	”This entity spans 12,431 member owners. Listing trademarks across members is limited to entities with 10,000 member owners or fewer.”	An `entity_id` / `entity_group` filter, or `GET /v1/entities/{id}/trademarks`, hit a cap.	Narrow the query, or query a specific member via `GET /v1/owners/{id}/trademarks`. Not retryable as-is.
429	`rate_limited`	Yes	Rate limit exceeded	”Rate limit exceeded. Retry after 30 seconds.”	Too many requests within the rate limit window	Wait for `retry_after` seconds, then retry. See Rate Limits.
500	`internal_error`	Yes	Internal server error	”An unexpected error occurred.”	Server-side bug or transient failure	Retry with exponential backoff. If the error persists, report it via `POST /v1/feedback` with the response’s `request_id` (or email support@signa.so).
502	`upstream_error`	Yes	Bad gateway	”The upstream service failed to respond.”	A backend dependency or office connector returned an invalid or failed response	Retry shortly with backoff. If it persists, report it via `POST /v1/feedback` with the response’s `request_id` (or email support@signa.so).
503	`service_unavailable`	Yes	Service unavailable	”Database is temporarily unavailable.”	A backend dependency is down	Wait for `retry_after` seconds, then retry. If the errors persist, report it via `POST /v1/feedback` with the `request_id` (or email support@signa.so).
504	`timeout`	Yes	Query timeout	”The request took too long to process. Please retry or narrow your filters.”	A database query exceeded the server-side statement timeout because the filters were too broad or the result set too large	Retry, or narrow your filters to reduce work. If it persists, report it via `POST /v1/feedback` with the response’s `request_id` (or email support@signa.so).
504	`preview_timeout`	No	Preview Timeout	”The preview could not produce a result within the server-side time budget.”	A `POST /v1/watches/preview` query was too heavy to evaluate within the roughly 20 second budget	Do not blind-retry (`retryable: false`). Narrow the query: add office or jurisdiction filters, reduce `trial_window_days`, or scope `filters.trademarkIds`. See Preview Watch.

entity_too_large carries an error.reason discriminator so you can branch without parsing the message: member_owners_too_large means the entity or group resolved to more member owners than the cap (the error also carries member_count and member_count_limit), and family_graph_too_large means the GLEIF family-graph walk exceeded its node or depth bound before owners were counted, which only fires on ?entity_group= (the error carries related_entity_limit and depth_limit). Either way, narrow the query with additional filters, query a specific member directly, or use ?entity_id= for a single entity instead of ?entity_group=; the caps bound fan-out cost and are not retryable as-is.

Edge-generated errors

A small set of errors is generated at the edge (CDN and security layer), before the request reaches the API. They use the same JSON envelope, with three differences:

request_id is a static sentinel: the edge cannot mint per-request IDs. Security blocks, oversized payloads, and edge rate limits use req_unknown; the static 502/503 pages served when the API origin is unreachable use req_edge_static_502 and req_edge_static_503.
The instance and suggestion fields are omitted: the edge cannot know them for your specific request.
To correlate an edge error with support, quote the x-amz-cf-id response header and the timestamp of the request instead of a request_id.

Edge-generated errors you may see: edge_rejected (403), payload_too_large (413, for bodies over 8 KB on any endpoint except image upload), rate_limited (429, when the edge rate limit trips before the API’s own limiter), and static bad_gateway (502) / service_unavailable (503) pages when the API origin is unreachable.

A few edge cases return HTML, not JSON. A request URI longer than the CDN’s length cap returns 414 with an HTML body. Oversized or malformed request headers return 400 with an HTML body (from the load balancer), or 494 with an HTML body when they exceed the CDN’s larger header cap. These responses come from infrastructure request parsers and cannot be converted to the JSON envelope. If you hit one with a request you believe is valid, email support@signa.so with the x-amz-cf-id response header (when present) and the timestamp.

Handling Errors

Errors return non-2xx status codes. The response body contains a structured error object and a top-level request_id, with the HTML exceptions noted in Edge-generated errors above (oversized URIs return 414, and oversized or malformed headers return 400 or 494, all with HTML bodies). Robust clients check the Content-Type header before parsing the body as JSON.

curl -s -w "\nHTTP Status: %{http_code}\n" \
  https://api.signa.so/v1/trademarks/tm_nonexistent \
  -H "Authorization: Bearer sig_YOUR_KEY"

The TypeScript SDK exposes typed error classes for each status code. See the TypeScript SDK reference for instanceof patterns and automatic retries.

Reporting a persistent server error

Server faults (500 internal_error, 502 upstream_error, 503 service_unavailable, 504 timeout) carry a suggestion that points you at the feedback channel. If retrying with backoff does not clear the error, submit it to POST /v1/feedback with the response’s request_id. Signa snapshots the matching request log onto the report, so the team can investigate exactly what you hit. Client errors (4xx) never carry this hint, they are fixed on your side by correcting the request. See Submit Feedback for the full flow.

Idempotency and `409 Conflict`

Mutating requests (PATCH, DELETE, and non-exempt POST) require an Idempotency-Key header (1-255 characters of [A-Za-z0-9_-]):

PATCH /v1/organization/api-keys/key_abc123
Idempotency-Key: rename-prod-key-2026-03-24-001

A key is bound to the exact request it first executed: the request URL and the request body. Same key + same URL + same body = cached response replayed (safe to retry). Replays carry an Idempotent-Replayed: true response header and preserve the original request_id. Same key + different body, or the same key against a different URL = 409 conflict error. Reusing one key across DELETE /v1/watches/wat_1 and DELETE /v1/watches/wat_2 conflicts rather than replaying the first delete — generate a fresh key for each distinct request. Same key while the first request is still in flight = 409 idempotency_processing: wait for the original to finish, then retry. Idempotency keys are scoped to your organization and expire after 24 hours. Only successful (2xx) responses are cached, so a failed request never pins you to its error.

curl -s -X PATCH https://api.signa.so/v1/organization/api-keys/key_abc123 \
  -H "Authorization: Bearer sig_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-key-123" \
  -d '{"name": "Production key (renamed)"}'

A handful of read-shaped POST endpoints are exempt by design: they exist as POSTs only because their query bodies are too large or complex for a URL, and they create nothing:

POST /v1/trademarks (search)
POST /v1/trademarks/batch (batch lookup)
POST /v1/suggest (and other suggest endpoints)
POST /v1/watches/preview (dry-run match count)
POST /v1/alerts/lookup (bulk read by IDs)

On exempt endpoints the header is optional and not replayed, but if you do send one, its format is still validated (1-255 characters of [A-Za-z0-9_-]); a malformed value returns 400 even there.

POST /v1/organization/api-keys and POST /v1/organization/api-keys/{id}/rotate are not exempt. Replay is the correct semantic for endpoints that mint one-time secrets: retrying the same Idempotency-Key returns the same secret instead of minting a second credential.

See Resilience and Retries → Idempotent Requests for the full exemption list and a worked retry example.

Troubleshooting by Symptom

I'm getting 401 on every request

Check your Authorization header format. It must be Authorization: Bearer sig_YOUR_KEY (with the Bearer prefix). Common mistakes:

Missing Bearer prefix: Authorization: sig_YOUR_KEY
Wrong key prefix: only keys of the form sig_{48 hex chars} are accepted. Any other prefix is rejected with 401 before any database lookup.
Expired key: check expires_at on your API key
Revoked key: check the API key status in your dashboard

I'm getting 403 'insufficient scope'

Your API key is valid but does not have the required scope for this endpoint. Each endpoint requires specific scopes:

Trademark search, list, and entity GET endpoints need trademarks:read
The event feed (/v1/events) needs events:read
Watches, alerts, webhooks, and portfolios need portfolios:manage
API key management needs api-keys:manage
Usage, plan, and log endpoints need billing:read

Create a new key with the needed scopes or update your existing key.

I'm getting 400 'validation_error' but my request looks correct

Common causes:

Missing required filter: GET /v1/trademarks requires at least one filter (no unscoped list queries).
Wrong date format: Use ISO 8601 (2026-03-24 or 2026-03-24T12:00:00Z).
Array syntax: Bracketed keys (e.g. offices[]=US) are not accepted; repeated keys (e.g. offices=US&offices=EM) are accepted as a fallback, but the canonical form is comma-separated (offices=US,EM).
Date range syntax: Use flat underscore operators, not brackets: ?filing_date_gte=2020-01-01&filing_date_lt=2025-01-01.
Boolean values: Only the literal strings true and false are accepted. 1, 0, yes, no, and TRUE all return a validation error.
application_number without office: When filtering by application_number or registration_number, you must also specify office.
Missing Idempotency-Key: Mutating requests (PATCH, DELETE, and non-exempt POSTs) require this header. Read-shaped POSTs (search, batch, suggest, watch preview, alert lookup) do not.

I'm getting 410 'entity_merged' for an owner I used yesterday

Entity resolution runs periodically. When two owner records are identified as the same entity, one is merged into the other. The 410 response includes a merged_into field pointing to the canonical record.Update your cached ID to the new one. All trademarks previously associated with the old owner are now under the canonical record.Resolved entities (ent_*) can also 410. When two resolved entities are fused, the loser’s ent_ id returns 410 entity_merged with the successor in merged_into: follow that field to the canonical record. An entity id for an owner that has since been linked to a company profile does not 410; it transparently resolves to the real entity (the returned id may differ from the one you requested).

Search returns different results than the detail endpoint

This is expected behavior due to the eventual consistency model. Search results are eventually consistent (typically under 30 seconds lag after a write), while detail endpoints are immediately consistent.If you just updated a record, wait a few seconds and retry the search. For time-sensitive workflows, use the detail endpoint as the source of truth.

I'm hitting rate limits during bulk operations

For bulk lookups, use Batch Retrieve (up to 100 IDs per request) instead of individual GET requests. This counts as one request against your rate limit.For search-heavy workloads, consider caching results on your side, using cursor pagination instead of re-executing searches, or upgrading your plan.

I'm getting 503 errors intermittently

This indicates a transient backend issue. The error is retryable: wait for the retry_after period and retry with exponential backoff. If 503 errors persist for more than a few minutes, email support@signa.so with a request_id from one of the failed calls.

Overview

Trademarks

Parties

Records

Intelligence

Filing & docketing

Monitoring

Analytics

Reference

Administration

SDK

Error Response Structure

Error Catalog

Edge-generated errors

Handling Errors

Reporting a persistent server error

Idempotency and `409 Conflict`

Troubleshooting by Symptom

​Error Response Structure

​Error Catalog

​Edge-generated errors

​Handling Errors

​Reporting a persistent server error

​Idempotency and 409 Conflict

​Troubleshooting by Symptom

Error Response Structure

Error Catalog

Edge-generated errors

Handling Errors

Reporting a persistent server error

Idempotency and `409 Conflict`

Troubleshooting by Symptom