Docs·Getting started·Errors & rate limits
Errors & rate limits
Failures are explicit and typed — Goable never serves a stale-cache score silently.
Error envelope
Every error response shares one shape:
{
"error": "VALIDATION_ERROR",
"message": "window.to must be after window.from",
"detail": { issues: [ … ] }
}Status codes
| Status | Code | Meaning |
|---|---|---|
| 400 | INVALID_REQUEST | Payload failed Zod validation. detail.issues[] lists each failing path. |
| 401 | UNAUTHORIZED | Bearer token absent, malformed, or hash mismatch. Rotate the key. |
| 402 | PAYMENT_REQUIRED | Endpoint needs a higher plan. Ensemble + projections are Pro / Scale. |
| 403 | FORBIDDEN | Authenticated but missing the required scope (or tenant suspended). |
| 429 | RATE_LIMITED | Daily quota exhausted for the tenant. Resets at 00:00 UTC. |
| 503 | PROVIDER_DEGRADED | Every provider in the chain failed within the timeout budget. |
Retries
Retry 429 and 503 with exponential backoff. 4xx other than 429 are deterministic — fix the request rather than retrying. The SDK throws GoableApiError (carrying status + code) for non-2xx and GoableNetworkError for transport failures.
Rate limits
A daily window per tenant, by plan; the counter resets at 00:00 UTC.
| Free | 100 / day |
| Starter | 1,000 / day |
| Pro | 10,000 / day |
| Scale | Unlimited |