Errors & retries
Every status freesea returns, and the right response to each.
Errors share one shape:
{ "error": { "status": 429, "message": "search backend rate limit reached; retry shortly" } }| Status | Meaning | What to do |
|---|---|---|
400 | Request failed validation | Read message — it names the offending field. Do not retry unchanged. |
401 | Key missing, malformed, or revoked | Get a fresh key from the dashboard. Never retry in a loop. |
403 | Account suspended | Terminal. A new key will not help — the block is on the account. Stop and surface it. |
429 | Rate limited | Wait for Retry-After seconds, then retry once. |
502 | The search backend failed | Retry once. If it persists, surface it — do not hammer. |
503 | freesea is not configured or its auth backend is down | Surface it. Retrying will not help. |
Rate limit headers
429 responses carry standard headers:
Retry-After— seconds to waitX-RateLimit-Limit,X-RateLimit-Remaining,X-RateLimit-Reset
Two different rate limits
A 429 can come from either of two places, and the message distinguishes them:
- Your key's limit — freesea's own per-key budget.
- The search backend's limit — upstream capacity, shared across freesea.
The message reads
search backend rate limit reached.
Both are honest 429s and both are safe to retry after Retry-After.
403 — account suspended
A 403 means the key is valid but the account it belongs to is suspended,
so every key on that account is refused. Rotating the key, creating a new one,
or signing up again with the same email will not restore access — the email is
blocklisted at the same time.
The reason is shown on the dashboard. If you think it is a
mistake, reply from the email address on the account to
alon@steelworks.software.