API Rate Limits & Error Codes
The error shape, every stable error code and what to do about it, rate-limit headers, and how to retry well.
Error shape
{
"error": { "code": "insufficient_scope",
"message": "This credential is missing the \"payments:read\" scope." },
"request_id": "req_8f1c2b…"
}Branch on code, show message to a human. The codes are stable:
| Code | Status | Meaning |
|---|---|---|
| unauthorized | 401 | No credential was sent. The response carries the OAuth discovery pointer. |
| invalid_credential | 401 | Wrong, expired or revoked. Do not retry — mint a new one. |
| insufficient_scope | 403 | Valid credential, missing permission. Re-grant, do not retry. |
| test_mode | 403 | A test key tried to change a record. |
| ip_not_allowed | 403 | The key has an IP allowlist and you are not on it. |
| plan_required | 403 | The workspace has put API access behind a plan. |
| not_found | 404 | No such record, or it is outside what this credential can see. |
| rate_limited | 429 | Too fast. Honour Retry-After and back off. |
| quota_exceeded | 429 | The monthly allowance for this credential is spent. |
| server_error | 500 | Our fault. Retry with backoff and quote the request_id. |
Rate limits
Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the window rolls). A 429 adds Retry-After — wait that long rather than retrying immediately. Each key can carry its own per-minute limit and a monthly cap; the defaults are shown on the API keys screen.
Retrying well
Retry 429 and 5xx with exponential backoff. Never retry 401, 403 or 404 — nothing about the outcome will change, and a retry loop against a 401 looks exactly like an attack.
Related guides
Related features and guides
- API Requests & Responses — Documentation. The response envelope, paging, the money and date conventions, and how writes work on the Seayora REST API.
- API Authentication & API Keys — Documentation. The three credentials Seayora accepts, live versus test keys, what a credential can see, and how to keep keys safe.
- Permissions Reference — Documentation. Every permission an assistant or API key can hold, what it unlocks, and which ones can change records — generated from the server.