Errors and rate limits
Error envelope, codes and rate-limit headers.
Error shape
Every failure from /api/v1 has the same envelope and a matching HTTP status:
{
"error": {
"code": "validation_failed",
"message": "Request validation failed",
"requestId": "6055d634-4535-4242-88a0-cddb0c1fe885",
"details": {
"issues": [
{
"location": "body",
"path": ["email"],
"code": "invalid_string",
"message": "..."
}
]
}
}
}
Branch on code, show your own text, and quote requestId to support. The
same id is in the x-request-id response header. Messages are for developers
and may change; codes are stable. New codes may be added, so keep a default
branch.
Codes
| Status | code | Meaning and what to do |
|---|---|---|
| 400 | invalid_json | Body is not JSON. Fix the request. |
| 400 | invalid_cursor | Pagination cursor is malformed. Restart from the first page. |
| 400 | bad_request | Other malformed input. |
| 401 | unauthorized | Missing, malformed, unknown or revoked key. One message for all, by design. |
| 402 | plan_limit_reached | Free plan cap (2 waitlists, 1,000 signups per waitlist). details has limit and plan. |
| 403 | forbidden | Publishable key on a secret-only route, or request Origin not in the project's allowed origins. |
| 404 | not_found | Unknown id, another project's id, or an erased signup. |
| 409 | conflict | Slug taken, too many endpoints, delivery already pending, signup already confirmed. |
| 409 | waitlist_archived | Join on an archived waitlist. Restore it to accept signups again. |
| 413 | payload_too_large | Body over the size limit. |
| 415 | unsupported_media_type | Send Content-Type: application/json. |
| 422 | validation_failed | A field is invalid; see details.issues for each. |
| 422 | abuse_blocked | Captcha, disposable or undeliverable email. Intentionally generic; see anti-abuse. |
| 422 | invalid_webhook_url | Endpoint URL is not https or points at a private address. |
| 429 | rate_limited | Too many requests. Wait Retry-After seconds. |
| 503 | rate_limiter_unavailable | Join/status limiter storage is down. Retry after Retry-After. |
| 500 | internal_error | Our fault. Retry with backoff; quote requestId if it persists. |
In the SDK
Each failure is a typed GetWaitError (with code, status, requestId):
| Class | Raised for |
|---|---|
ValidationError | 422 validation_failed (.issues) |
AbuseBlockedError | 422 abuse_blocked |
AuthError | 401, 403 |
NotFoundError | 404 |
PlanLimitError | 402 |
RateLimitError | 429 (.retryAfter seconds) |
NetworkError / TimeoutError | no response |
SecretKeyRequiredError | secret-only call with a gw_pk_ key (before any request) |
The SDK retries network errors, timeouts, 429 and 5xx (2 retries by
default, exponential backoff with jitter, honoring Retry-After). Joining is
idempotent, so a retried join is safe. See
packages/getwait-sdk.
Rate limits
Counted per minute, shared across all servers. Every request counts, including rejected ones.
| Route | Limit |
|---|---|
Join (POST /waitlists/:id/signups) | 10 per IP per minute, 3 per (IP, email) |
| Status by referral code | 30 per IP per minute |
| Confirm / remove links | 30 per IP per minute |
| Resend confirmation | 600 per key; 3 per signup per day |
| Export | 5 per hour per key |
| Dashboard export | 5 per hour per account |
| Every other keyed route | 600 per key per minute |
Limited routes return RateLimit-Limit, RateLimit-Remaining and
RateLimit-Reset headers. A 429 adds Retry-After. IPv6 clients are
limited per /64. The client IP is taken from the header named by
TRUSTED_IP_HEADER, never from a client-supplied X-Forwarded-For.
Calling join from your server. Join limits are per client IP. If your server joins people on their behalf, every join shares your server's IP and hits the 10-per-minute cap quickly. Call join from the visitor's browser with a publishable key, or forward the visitor's IP through a header your GetWait deployment trusts.