The HTTP status always matches the code.
Two responses have no JSON body: a request with the wrong method for its path returns
405 Method Not Allowed, and a request to /v1/stream without WebSocket upgrade headers returns a plain-text 4xx.
Error codes
New codes may be added. Handle an unrecognized code according to its HTTP status.
Validation details
Only two codes includedetails. UNSUPPORTED_CHAIN includes {chain}, and VALIDATION_ERROR includes a list of {field, message} objects, one per problem, as in the example at the top of this page. field is the parameter name as sent in the request, or path, query or body when the problem is not tied to a single field.
Limits
Limits are set well above normal use. Reaching one usually indicates a retry loop or leaked stream connections.
All keys of one organization share a single request budget. Your plan, or an agreement for your organization, can set another rate, including a separate rate for one endpoint. Each session token has its own stream connection, subscription and address limits, equal to its key’s, and counts against its key’s request budget.
The request budget refills continuously, at one request every tenth of a second for a rate of 10 per second, and allows a burst of at most one second’s worth of requests. Limits are not applied per IP address, so multiple servers behind one outbound IP are limited only by their key’s budget. Design your client to stay well below these values.
A stream connection counts against your key from its handshake until it closes, and frames sent over a connection do not consume request budget. The 20 subscriptions belong to the key rather than to a connection, so a single connection can hold all of them.
GET /openapi.json requires no key, consumes no budget, and returns no X-RateLimit-Remaining header.
Credits
Each successful (2xx) request costs one credit, and so does each stream update frame. Error responses, the stream handshake, and the ack, exit, error and pong frames cost nothing. A narrower stream filter, throttleMs and closedOnly each send fewer frames, so they cost less.
When an organization has used the credits its plan includes for the billing period:
- Every request with any of its keys returns
402 CREDITS_EXHAUSTED, including the stream handshake. - Its open stream connections close with code
4402. - Requests succeed again when the next billing period starts or the plan is upgraded.
Response headers
X-RateLimit-Remaining reports the remaining requests in the budget this request counted against. It is absent from a 401, because the request has no valid key, and from a 503 returned when the key could not be validated.
Use X-RateLimit-Remaining to pace your client and slow down before you reach the limit.
Retry strategy
- Respect
Retry-After. Wait at least the number of seconds it specifies. - Use exponential backoff with jitter on
500and503, so parallel workers do not retry in sync. - Limit retries. Three to five attempts are enough; beyond that, the problem needs investigation.
- Do not retry a
4xxother than429. The request fails the same way every time.
Request IDs
Every response includes anX-Request-ID header. You can also send your own X-Request-ID of up to 128 visible ASCII characters with no spaces, and the API returns it unchanged. An invalid value is replaced with a generated ID rather than rejected.
When you contact support about a failed request, include its X-Request-ID.
Stream errors
When the API rejects a stream frame, it returns anerror frame with the same code, message and details fields. See WebSocket streams.