Errors and limits
Error shape
Errors Spend Gateway raises are JSON with one field:
{"error": "unknown grant"}
401is always{"error":"unauthorized"}. It doesn’t say why.5xxis always{"error":"internal error"}; details are kept out of responses.- Other messages are written for people and may change. There are no error codes.
curl -sS https://fwkl7sygagsdlb6ut3lsomjmvi0qvyyt.lambda-url.us-east-1.on.aws/v1/spend/usage | grep -Fx '{"error":"unauthorized"}'
Some errors are not JSON. They come from request parsing, after Spend Gateway has accepted your token, and are plain text:
| Status | Cause | Example body |
|---|---|---|
400 | A path id is not a UUID | Invalid URL: Cannot parse `grant_id` with value `not-a-uuid`: ... |
400 | The body is not valid JSON | Failed to parse the request body as JSON: ... |
413 | The body is larger than 2 MB | |
415 | A body sent without Content-Type: application/json | Expected request with `Content-Type: application/json` |
422 | A field is missing, has the wrong type, or has a value not allowed | Failed to deserialize the JSON body into the target type: period: unknown variant `week`, expected one of `day`, `month`, `never` ... |
Spend Gateway checks your token before it parses anything else, so without an
accepted token each of these is a 401 instead, even a path id that is not a
UUID:
curl -sS https://fwkl7sygagsdlb6ut3lsomjmvi0qvyyt.lambda-url.us-east-1.on.aws/v1/spend/grants/not-a-uuid/balance | grep -Fx '{"error":"unauthorized"}'
A path that doesn’t exist is 404 with an empty body.
Status codes
| Status | Meaning |
|---|---|
200, 201, 204 | Done. Creating a grant returns 201; revoking returns 204. |
400 | A field breaks a rule: "settlement": "Free", Byok without a period, or an app_id that is empty or over 128 bytes. |
401 | No token, or one Spend Gateway does not accept. |
404 | No such grant, or not yours. Spend Gateway does not say which. |
409 | A new grant for an app that already has an active one, or that would be the owner’s 101st (see Grants); a new limit below the grant’s debited plus reserved; or a change to a revoked grant. |
5xx | Something failed inside Spend Gateway. Retry later. |
Limits
- Request body: 2 MB.
- Grants: 100 per owner, live or still holding a reservation.
- Rate limits: Spend Gateway has none of its own.
- Lists are not paged; see Usage.