HTTP API errors
How the BuildBase HTTP API answers success and failure - the bodies, the HTTP statuses, the code field to branch on, and which requests are safe to retry.
In short
Every answer has a status, a three-digit number: 2xx means it worked, 4xx means something in the request needs changing, 5xx means BuildBase could not finish it. A failed answer also carries a sentence, message, that you can show a person, and often a code, a fixed word your program can check. Branch on the code and the status, never on the wording of the message.
What a success looks like
A success is 200 (or 201 for some creates) with a JSON body. Most routes answer the object or the list itself:
[{ "_id": "665f1c2e9b1d4a0012ab34cd", "name": "Acme" }]Some answer in an envelope, { "success": true, "data": ... }. Each route keeps the shape it has (Versioning and changes). A few older routes answer 200 with "success": false and a message for a refusal: treat success: false as a failure whatever the status, as the SDK does.
What a failure looks like
| Status | When | Body |
|---|---|---|
400 | A field failed validation, or an id in the path is not a valid id | { "error": true, "path": "<field>", "message": "..." } |
401 | The credential is missing, mistyped, expired or revoked. On the organization API, also a key or member whose role has no grant for the route's x-permission | The text Unauthorized, or JSON with a code where the gate says why, such as session_ended |
402 | The organization's plan does not cover this | code: NO_ACTIVE_PLAN, FEATURE_NOT_IN_PLAN, PLAN_LIMIT_REACHED (with limit and current) or QUOTA_EXHAUSTED |
403 | Signed in, but not allowed: a workspace role without the permission, a blocked account, a change that needs a fresh sign-in (reauth_required) | JSON with message, and a code where one applies |
404 | The id names nothing in this organization or environment, or no route has this path | { "error": true, "message": "..." }; an unknown path answers the text Not Found |
409 | It clashes with what exists: a duplicate, a hold no longer open, a request with the same Idempotency-Key still running | JSON with message, often a code |
422 | An Idempotency-Key reused for a different request | code: IDEMPOTENCY_KEY_REUSED |
429 | A rate limit was reached | { "success": false, "message": "...", "reason": "rate_limited", "retryAfter": 12 } |
500 | An unexpected failure | { "error": true, "code": "server_error", "message": "Internal server error", "requestId": "..." } |
503 | A failure the route caught (code: server_error), or a service it needs is briefly down (code: temporarily_unavailable, with Retry-After and retryAfterSeconds) | JSON with code and message |
OAuth endpoints answer in OAuth's own shape, { "error": "invalid_grant", "error_description": "..." } (OAuth endpoints).
A refusal with a code, from the token exchange:
{
"success": false,
"code": "impersonation_not_allowed",
"message": "This API key may not create a session for another user. Issue the key with an owner or admin role, or omit userId to create a session for the key's own user."
}Every code, with its status and what to do, is listed in Error codes.
Read an error in code
import requests
res = requests.get(
"https://api.console.buildbase.app/api/v1/public/workspaces",
headers={"x-session-id": session_id},
timeout=30,
)
if res.ok:
workspaces = res.json()
else:
body = res.json() if "json" in res.headers.get("content-type", "") else {}
print(res.status_code, body.get("code"), body.get("message") or res.text)
print("request id:", res.headers.get("x-request-id"))Quote the request id
Every response carries an x-request-id header, and a 500 repeats it in the body as requestId. Include it when you contact [email protected]: it names the one request in BuildBase's logs.
When a retry is safe
| You got | Retry? |
|---|---|
429 | Yes, after the seconds in Retry-After (or the body's retryAfter) |
503 with temporarily_unavailable | Yes, after Retry-After |
409 IDEMPOTENCY_IN_PROGRESS | Yes, shortly, with the same Idempotency-Key |
A timeout, a dropped connection, 500, 503 server_error | A GET yes. A write only with the same Idempotency-Key, or after reading back whether it happened |
400, 401, 402, 403, 404, 422 | No: the same request gets the same answer. Change the request or the credential first |
Back off between attempts: wait 1 second, then 2, then 4, and stop after a few tries. A write that took effect but whose answer was lost is the case Idempotency-Key exists for.
Next steps
- Error codes - every
code, its status and its remedy. - Idempotent requests - retry a payment or a refund without doing it twice.
- Rate limits - the limits behind a
429.