Read the status first
400: correct the input. 401: check the key. 403: access denied. 404: no available record for that number. 429: slow down or check your allowance. 5xx: a service failure; retry only with a bounded policy.
Do not assume one error envelope
Input validation uses Problem Details, while a 404 or rate rejection can have an empty body. Read the HTTP status before parsing JSON. Do not depend on a quota_exceeded JSON code or Retry-After header unless present.
Rate, volume and concurrency
These are separate limits. The public API uses a fixed one-minute rate window per client; additional keys do not create additional per-client rate allowance. Plan commercial limits are listed on the pricing page.
Retry responsibly
Respect Retry-After if returned. Otherwise use exponential backoff with jitter, a maximum delay and a retry limit. Never retry invalid input or invalid credentials indefinitely. A retried billable response counts again.
