Headers & errors
What comes back on every response, what each status code means, and the shape of an error body.
Every response through the gateway carries what the request cost and what it left in the balance, so an agent can answer "what did that cost?" without opening anything. Errors are either the provider's, passed through unchanged, or Squiid's, with a status that says which.
Response headers
| Header | What it carries |
|---|---|
x-sq-request-id | Unique id. Quote it to support; find it in the ledger; price it with GET /v1/requests/:id. |
x-sq-cost | Cost of this request in USD, e.g. 0.004120. On streams it is not a header: the last SSE line is a comment, : sq-cost=0.004120 sq-balance=142.18, which every parser ignores — or read it back from GET /v1/requests/:id. |
x-sq-balance | Remaining balance after this request. |
x-sq-provider-ms | Time spent waiting on the provider, so you can separate our latency from theirs. |
x-sq-limit-source | On a 429, whose rate limit was hit: yours or the provider’s. |
Status codes
| Status | What it means |
|---|---|
401 | Missing or revoked key. |
402 | Insufficient balance, or the key’s cap is reached. The body includes topup_url. |
403 | Key isn’t scoped to this service or resource. |
404 | The service segment names something you have not added to your account. |
429 | Your rate limit or the provider’s — x-sq-limit-source says which. |
5xx | Provider errors pass through unchanged and are never billed. |
The error body
Every error body Squiid produces has the same shape, with topup_url added on a 402:
{
"error": {
"type": "insufficient_balance",
"message": "Balance is $0.00. Top up to resume.",
"request_id": "req_8h2k…",
"topup_url": "https://app.squiid.io/usage"
}
}Provider errors are not rewritten into that shape. When the provider answers 400 or 422 with its own body, that body is what you get, because your SDK already knows how to read it — and it is never billed.
Base URL and auth, once more
- Base URL:
https://api.squiid.io/v1 - Header:
Authorization: Bearer $SQUIID_API_KEY - Keys are prefixed
sq_live_and are created in the console at app.squiid.io. - Unified models are named
provider/model; passthrough paths are the provider's own.
Every call,
priced on the way out.
Request id, cost and balance on the response. No reconciliation at the end of the month.