Errors & Rate Limits

Error shape

Every error response uses the same JSON shape:

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded: 60 requests per minute."
  }
}

code is a stable machine-readable string. message is human-readable and may change wording over time — branch logic on code, not on message.

Status codes

Status	When
`200`	Success
`400`	Malformed request — bad query parameter, invalid id format
`401`	Missing, malformed, expired, or revoked Bearer token
`403`	Token is valid but the owning account is no longer on the Enterprise tier
`404`	Resource not found OR outside your whitelist (same response — no leak)
`429`	Rate limit exceeded
`500`	Internal server error

Error codes

`code`	HTTP	Recovery
`missing_token`	401	Add `Authorization: Bearer <token>` header
`invalid_token`	401	Token is malformed, revoked, or doesn't exist. Generate a new one.
`tier_forbidden`	403	Your account is no longer on the Enterprise tier. Contact sales.
`bad_request`	400	Check your query parameters / path id format
`not_found`	404	The id is wrong OR outside your whitelist
`rate_limited`	429	Wait and retry — see `Retry-After` header
`internal_error`	500	Retry after a short backoff. Persistent? Email sales@ordertune.com.

Rate limits

Limits apply per API key, not per account. Generate separate keys for separate workloads if you need higher aggregate throughput.

Window	Default
Per minute	60 requests
Per day	10,000 requests

Every response carries informational headers:

X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 47
X-RateLimit-Limit-Day: 10000
X-RateLimit-Remaining-Day: 8429

When you hit a limit, the response is 429 with a Retry-After header in seconds:

HTTP/1.1 429 Too Many Requests
Retry-After: 47
Content-Type: application/json

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded: 60 requests per minute."
  }
}

Need higher limits? Contact sales — per-key limits are configurable per contract.

Authentication failures

401 responses also include a WWW-Authenticate header:

WWW-Authenticate: Bearer error="invalid_token"

This lets HTTP-client libraries surface the error reason without parsing the JSON body.

Idempotency and retries

All Enterprise API endpoints are GET requests and naturally idempotent. Retries on network failures or 5xx responses are safe.

For 429 responses, honor the Retry-After header — retrying inside the window will just consume your remaining budget without succeeding.

Caching

Responses carry Cache-Control: no-store. Do not cache responses on shared caches or CDNs.

For client-side polling, consult the tradeDate field on the response to decide whether you've already processed a given signal — every signal has a stable integer id that you can use as a deduplication key.

Audit log

Every request — successful or not — is logged in our append-only api_request_log for compliance and forensics. The log retains:

Timestamp, IP, User-Agent
Endpoint, method, status code, response byte count
Which key was used (or null for missing-token requests)

We retain at least 12 months. Disputes about "we never got a signal" are resolved from this log.

Endpoints Terms of Use