Rate limits, quotas & error handling

The monthly quota

On top of the per-second and per-hour rate limits, each key has a monthly request quota - a ceiling on how many requests it can make in a billing month. The rate limiter smooths traffic over short windows; the quota caps total volume over the month. You can exhaust the quota without ever tripping a rate tier, and when you do, requests fail with monthly_limit_exceeded until the quota resets or you raise it. Watch the X-Quota-* headers below to see how much of the month's budget is left.

Response headers to read

Every response carries the live rate-limit and quota counters. Read them proactively - warn or slow down as Remaining approaches zero, rather than waiting for the first 429. Note the two Reset conventions: the X-RateLimit-Reset value is an absolute Unix timestamp, while RateLimit-Reset is relative seconds from now.

Error taxonomy

Throttling and access failures use the same uniform envelope as every other reply: success is false, the detail moves under error, and a timestamp is always present. Branch on the stable error.code, never the human-readable message:

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after the period in the Retry-After header."
  },
  "timestamp": "2026-05-28T18:04:45"
}

Each error.code maps to an HTTP status, and tells you whether to retry or to fix something first:

Only 429 and 503 are safe to retry unchanged. Note that monthly_limit_exceeded can surface as 429 or, on some paths, 403 - either way it means the quota is spent, not that a short wait will help. For the credentials and access codes (401/403) see the Authentication guide; for insufficient_credits see Credits.

Recommended client behavior

Build one retry policy and apply it everywhere:

• Retry only 429 and 503, with exponential backoff (1s, 2s, 4s, ...) and a capped number of attempts.
• Always honor Retry-After when it is present - use its value instead of your computed delay.
• Surface the quota headers: warn before you hit the wall rather than after, using X-RateLimit-Remaining and X-Quota-Remaining.
• Do not retry 402, 401, or 403 - they need an action (credits, credentials, or access), not another call.

# Retry 429/503 with backoff; honor Retry-After when the server sends it.
attempt=0
while :; do
  code=$(curl -sS -D headers.txt -o body.json -w '%{http_code}' \
    "https://api.nyne.ai/person/enrichment?request_id=$RID" \
    -H "X-API-Key: $KEY" -H "X-API-Secret: $SECRET")

  case "$code" in
    2*) break ;;                      # done
    429|503)
      retry=$(grep -i '^Retry-After:' headers.txt | tr -d '\r' | awk '{print $2}')
      # Prefer Retry-After; otherwise exponential backoff (1s, 2s, 4s, ...).
      sleep "${retry:-$(( 2 ** attempt ))}"
      attempt=$(( attempt + 1 )) ;;
    401|402|403) echo "not retryable - fix creds/credits/access"; break ;;
    *) echo "unexpected $code"; break ;;
  esac
done

What's next

• Credits - how usage is metered and when a request consumes a credit.
• Authentication - keys, secrets, IP-locking, and the auth error codes.
• Async requests - the submit-and-poll lifecycle that must respect these limits.
• Responses - the uniform envelope every reply shares.