Skip to content
BuildBase
HTTP API menu

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

StatusWhenBody
400A field failed validation, or an id in the path is not a valid id{ "error": true, "path": "<field>", "message": "..." }
401The 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-permissionThe text Unauthorized, or JSON with a code where the gate says why, such as session_ended
402The organization's plan does not cover thiscode: NO_ACTIVE_PLAN, FEATURE_NOT_IN_PLAN, PLAN_LIMIT_REACHED (with limit and current) or QUOTA_EXHAUSTED
403Signed 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
404The 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
409It clashes with what exists: a duplicate, a hold no longer open, a request with the same Idempotency-Key still runningJSON with message, often a code
422An Idempotency-Key reused for a different requestcode: IDEMPOTENCY_KEY_REUSED
429A rate limit was reached{ "success": false, "message": "...", "reason": "rate_limited", "retryAfter": 12 }
500An unexpected failure{ "error": true, "code": "server_error", "message": "Internal server error", "requestId": "..." }
503A 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

read_error.py
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 gotRetry?
429Yes, after the seconds in Retry-After (or the body's retryAfter)
503 with temporarily_unavailableYes, after Retry-After
409 IDEMPOTENCY_IN_PROGRESSYes, shortly, with the same Idempotency-Key
A timeout, a dropped connection, 500, 503 server_errorA GET yes. A write only with the same Idempotency-Key, or after reading back whether it happened
400, 401, 402, 403, 404, 422No: 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