Errors & rate limits
When a request fails, the Ranksy API returns a consistent error envelope alongside an appropriate HTTP status code. The code is a stable, machine-readable string you can branch on; the message is human-readable and may change.
Error envelope
Every error response wraps a single error object. The type groups related codes (for example invalid_request_error or authentication_error); code is the specific, stable identifier; message explains what happened; param (when present) names the first offending field; and doc_url links to this reference, anchored at the failing code.
- Name
type- Type
- string
- Description
The error category, e.g.
invalid_request_error,authentication_error,permission_error,integration_error.
- Name
code- Type
- string
- Description
The stable, machine-readable error code (see below).
- Name
message- Type
- string
- Description
A human-readable description. Do not parse this.
- Name
param- Type
- string
- Description
Present on validation errors: the name of the first failing query parameter.
- Name
doc_url- Type
- string
- Description
Link to the documentation for this code:
https://docs.ranksyapp.com/errors/{code}.
Error response
{
"error": {
"type": "invalid_request_error",
"code": "validation_failed",
"message": "end_date must be greater than or equal to start_date.",
"param": "end_date",
"doc_url": "https://docs.ranksyapp.com/errors/validation_failed"
}
}
Error codes
Each code below has an anchor matching its code string, so doc_url (https://docs.ranksyapp.com/errors/{code}) links straight here.
validation_failed
One or more query parameters are invalid — a malformed date, end_date earlier than start_date, an out-of-range per_page, an unknown granularity, and so on. The param field names the first failing field.
unknown_metric
The {metric} in the path is not one of the 12 catalog metrics.
unsupported_basis
The basis value is not valid for the requested metric. For example, only ltv accepts month / year, and only churn_rate accepts real_churn. Metrics that ignore basis never raise this.
missing_team_scope
The key is valid but is not bound to a team, so no apps can be resolved. (A missing or invalid key also returns 401.)
insufficient_permissions
The key is valid and team-scoped but lacks the metrics:read (or *) scope required to read metrics.
partner_integration_not_connected
The app's Shopify Partner integration has not been connected, so no partner metrics can be served.
partner_integration_unauthorized
The app's Shopify Partner integration was rejected or its authorization was revoked. Reconnect it in Ranksy.
partner_integration_pending
The app's Shopify Partner integration is still initializing. The first sync has not completed yet; retry once it finishes.
Rate limits
Requests are rate-limited per key on two windows simultaneously:
- Name
Per minute- Type
- 120 requests
- Description
A rolling per-minute limit of 120 requests.
- Name
Per day- Type
- 50,000 requests
- Description
A per-day limit of 50,000 requests.
Unauthenticated requests (such as the health check) fall back to a per-IP limit.
Every response carries standard X-RateLimit-* headers so you can track your remaining budget:
Rate-limit headers
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1716998400
When you exceed a limit, the API responds with 429 Too Many Requests and a Retry-After header indicating how many seconds to wait before retrying:
429 response headers
HTTP/1.1 429 Too Many Requests
Retry-After: 12