Error Reference

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": "https://api.signa.so/errors/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	Error type URI (stable identifier for programmatic use)
`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

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.
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_live_xxx` 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/api-keys/{id}`.
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 ‘abc123’ was already used with a different request body.”	Reusing an `Idempotency-Key` header 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 body.
410	`entity_merged`	No	Entity merged	”Owner own_old123 has been merged into own_abc123.”	The entity was deduplicated via entity resolution. The old ID is permanently redirected.	Follow the `merged_into` field in the error response to the canonical entity. Update any cached references.
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. Consider implementing exponential backoff. Check `RateLimit` response headers to monitor your remaining quota.
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, contact support with the `request_id`.
503	`service_unavailable`	Yes	Service unavailable	”Database is temporarily unavailable.”	A backend dependency (PostgreSQL, OpenSearch, Valkey) is down	Wait for `retry_after` seconds, then retry. Check status.signa.so for ongoing incidents.

Handling Errors in Code

# Errors return non-2xx status codes
curl -s -w "\nHTTP Status: %{http_code}\n" \
  https://api.signa.so/v1/trademarks/tm_nonexistent \
  -H "Authorization: Bearer sig_live_xxx"

Rate Limit Headers

Every response includes rate limit information via IETF standard headers:

RateLimit-Policy: 1000;w=60
RateLimit: remaining=942, reset=30

On a 429 response, the Retry-After header tells you exactly how long to wait:

HTTP/1.1 429 Too Many Requests
Retry-After: 30

Rate limits by tier:

Tier	Endpoints	Default Limit
`tier-1-reads`	All GET endpoints	1,000/min
`tier-2-search`	`GET` and `POST /v1/trademarks` (collection)	200/min
`tier-3-writes`	All POST/PATCH/DELETE	100/min

Higher-plan organizations receive multiplied limits. Your actual limits are always reflected in the RateLimit-Policy header.

Idempotency and `409 Conflict`

All mutating requests (POST, PATCH, DELETE) require an Idempotency-Key header:

POST /v1/watches
Idempotency-Key: create-watch-2026-03-24-001

Same key + same body = cached response replayed (safe to retry). Same key + different body = 409 Conflict error. Idempotency keys are scoped to your organization and expire after 24 hours.

curl -s -X POST https://api.signa.so/v1/watches \
  -H "Authorization: Bearer sig_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-key-123" \
  -d '{"name": "My Watch", "query": "SIGNA"}'

Troubleshooting by Symptom

I'm getting 401 on every request

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

Missing Bearer prefix: Authorization: sig_live_xxx
Using test key in production: sig_test_xxx keys only work in test mode
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
Event endpoints need events:read
Portfolio/watch CRUD needs portfolios:manage
API key management needs api-keys:manage

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[]=uspto) are not accepted; repeated keys (e.g. offices=uspto&offices=euipo) are accepted as a fallback, but the canonical form is comma-separated (offices=uspto,euipo).
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: All POST/PATCH/DELETE requests require this header.

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.

Search returns different results than the detail endpoint

This is expected behavior due to the eventual consistency model. Search reads from OpenSearch (eventually consistent, typically under 30 seconds lag), while detail reads from PostgreSQL (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 POST /v1/trademarks/batch (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
Upgrading to a higher plan tier for increased limits

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, check status.signa.so for ongoing incidents.

Getting Started

Core Concepts

How Signa Works

Use Cases

Working with the API

Trust & Compliance

Error Response Structure

Error Catalog

Handling Errors in Code

Rate Limit Headers

Idempotency and `409 Conflict`

Troubleshooting by Symptom

Getting Started

Core Concepts

How Signa Works

Use Cases

Working with the API

Trust & Compliance

​Error Response Structure

​Error Catalog

​Handling Errors in Code

​Rate Limit Headers

​Idempotency and 409 Conflict

​Troubleshooting by Symptom

Error Response Structure

Error Catalog

Handling Errors in Code

Rate Limit Headers

Idempotency and `409 Conflict`

Troubleshooting by Symptom