Errors, rate limits & pagination

The API uses conventional HTTP status codes and returns a JSON body on every error. Read the status code first to decide whether to fix the request, back off, or retry.

#Error format

Errors carry a single detail field describing what went wrong:

{
  "detail": "Missing API key. Provide X-API-Key header or Authorization: Bearer <key>"
}

Validation errors (malformed or out-of-range parameters) return a structured list:

{
  "detail": [
    {
      "loc": ["query", "granularity"],
      "msg": "value is not a valid enumeration member; permitted: 'day', '3h'",
      "type": "type_error.enum"
    }
  ]
}

#Status codes

• 200 OK — success; the body is the resource.
• 400 Bad Request — a parameter is present but unusable.
• 401 Unauthorized — missing or invalid API key. See Authentication.
• 403 Forbidden — the key isn’t scoped to the requested market.
• 404 Not Found — no resource with that id.
• 422 Unprocessable Entity — a query parameter failed validation (wrong type, bad enum, out of range).
• 429 Too Many Requests — you’ve exceeded the rate limit; back off and retry.
• 503 Service Unavailable — a dependency is briefly degraded. Retry after Retry-After; not a client error.

#Rate limits & quotas

Limits are set by your plan. On the current Pro plan:

• 1,000,000 requests / month included, across every endpoint family.
• 500 requests / minute rate limit.
• Up to 10 API keys, each independently scoped and revocable.

You’ll get email + Slack alerts as you approach your monthly quota. Need more? Talk to sales about higher quotas, on-prem or custom SLAs.

#Pagination

List endpoints return a bounded page of results. Most accept limit (page size, with a sensible default and maximum) and offset (how many to skip); the v2 feed additionally supports cursor paging for stable, gap-free iteration. Each endpoint’s reference lists its exact paging parameters and defaults.

# page 2, 50 per page
curl "https://d2tr.com/api/v1/entities?region=us&limit=50&offset=50" \
  -H "X-API-Key: $D2TR_API_KEY"