Spinwheel returns HTTP 429 for two different reasons:
- Request-rate limits protect the platform. You hit them by sending too much traffic, and they clear within a minute.
- Business limits protect the consumer and the bureau relationship — typically one credit pull per user per day, five One-Time Passcode (OTP) attempts per code. These have nothing to do with how fast you are sending, and they will not clear on backoff.
Most 429s here are the second kind, so check status.desc to tell them apart before retrying.
Request-rate limit
Request-rate limits may vary depending on the API key.Sandbox and production keys have separate allowances. For details, reach out to your Spinwheel representative.
Business limits
| Limit | status.desc | Where |
|---|---|---|
| One Debt Profile per user per day | DAILY_USER_REQUEST_LIMIT_REACHED | Request a Debt Profile |
| Five OTP attempts per code | MAX_ATTEMPTS_REACHED | Verify an SMS Connection |
| Too many verifications for a number | TOO_MANY_REQUESTS | Verify an SMS Connection |
| Number blocked for 24 hours | TOO_MANY_VERIFICATIONS | Connect a User via SMS |
One Debt Profile per user per day
POST /v1/users/USERID/debtProfile pulls a real credit report, so it is capped at one request per user per day. A second call the same day returns 429 DAILY_USER_REQUEST_LIMIT_REACHED.
Read the cached profile with Retrieve a User instead, and if you need data to stay current on a schedule, use a refresh subscription rather than polling.
OTP attempts
An OTP is valid for 5 minutes and accepts 5 attempts. Past either, request a new OTP at POST /v1/users/connect/sms.
Repeated failures against the same phone number escalate: first TOO_MANY_REQUESTS, then TOO_MANY_VERIFICATIONS, which disables the number for 24 hours.