Reference
Errors and rate limits
Error codes returned by every endpoint, what causes them, and the request limits that apply.
Error format
Errors use the standard OAuth shape: a machine-readable error code and a human-readable error_description. Branch on error; the description can change. Authentication failures also set a WWW-Authenticate header.
HTTP/1.1 400 Bad RequestContent-Type: application/jsonCache-Control: no-store{ "error": "invalid_grant", "error_description": "The authorization code is invalid or expired."}Error codes
| Status | error | What happened |
|---|---|---|
| 400 | invalid_request | A required parameter is missing, repeated, or the body can't be parsed. Or you sent two client authentication methods. |
| 401 | invalid_client | Unknown or disabled client, wrong secret, or a secret is required for this token. |
| 400 | invalid_grant | The code or refresh token is invalid, expired, already used, issued to another app, or the founder disconnected. Also a redirect_uri or PKCE mismatch. |
| 400 | unsupported_grant_type | grant_type isn't authorization_code or refresh_token. |
| 401 | invalid_token | The access token is missing, malformed, expired or revoked. Refresh it, or sign the founder in again. |
| 403 | insufficient_scope | The token wasn't granted the scope this endpoint needs. |
| 429 | rate_limited | Too many requests. Wait until the reset time and retry. |
| 500 | server_error | Something went wrong on our side. Retry with backoff. |
Sign-in errors
Problems with the authorization request come back to your callback URL as ?error=…&error_description=…&state=….
| error | What happened |
|---|---|
access_denied | The founder chose not to allow your app. |
invalid_scope | The request asked for a scope that doesn't exist. |
invalid_request | A PKCE parameter is malformed, or code_challenge_method isn't S256. |
unsupported_response_type | response_type isn't code. |
login_required | prompt=none, and the founder isn't signed in to FoundrList. |
consent_required | prompt=none, and the founder hasn't approved these scopes yet. |
Bad client or callback URL? No redirect.
If the client ID is unknown or the redirect_uri isn't registered, FoundrList shows an error page instead of redirecting, so your app can never be used to bounce founders to another site.
Rate limits
| Endpoints | Limit |
|---|---|
| Token and revoke | 60 requests a minute per client and IP address |
| User info and spend | 300 requests a minute per client, and 600 per IP address |
| Spend by email | 300 requests a minute per client and IP address |
| Public product API | 400 requests a minute per IP address |
Responses include X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix time in milliseconds). Over the limit you get 429.
HTTP/1.1 429 Too Many RequestsX-RateLimit-Limit: 300X-RateLimit-Remaining: 0X-RateLimit-Reset: 1791273600000{ "error": "rate_limited", "error_description": "Too many requests. Slow down." }