Rate limits and errors

Free tier limits

Every key gets 30 requests per minute and 2,000 requests per day. prices_batch counts as one request no matter how many ids you send. GET /v1/usage is free and never counts against either limit; call it to check your remaining headroom.

When you exceed a limit, the response is 429 with Retry-After (seconds) and retry_after_seconds in the error body. rate_limit_exceeded means the per-minute limit tripped; quota_exceeded means the daily quota tripped. Back off and retry with the per-minute limit; wait for the next UTC day for the daily quota.

The error envelope

Every error is application/problem+json (RFC 9457):

{
  "type": "https://api.binderdex.com/errors/not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "Card not found.",
  "code": "not_found",
  "request_id": "req_9f2c1b7a"
}

Keep request_id when reporting an issue; never send your API key.

Status codes

| Status | Code | Meaning | | ------ | ----------------------------------------- | ------------------------------------------------------------------------------------------- | | 400 | invalid_request | A parameter or the request body failed validation. Fix the request; do not retry unchanged. | | 401 | unauthorized | The key is missing, malformed, or revoked. | | 403 | sandbox_key | The key is a sandbox key. Create a live key. | | 404 | not_found | No card or set matched the given id. | | 429 | rate_limit_exceeded or quota_exceeded | Respect Retry-After before retrying. | | 500 | internal_error | Unexpected failure. Keep the request id and retry with backoff. |

Caching

Card and set responses set Cache-Control with a short max-age; cards_get also sets ETag. Under the API Terms, do not cache prices beyond 24 hours.