Bluwing/Docsv0.9.0
Operational
API ReferenceConsole

Get started

  • Introduction
  • Quickstart
  • How it works

Build

  • Tool format
  • Matching hints
  • Toolsets and builds
  • Versions and live

Call

  • Resolve a request
  • Reading responses
  • OpenAI and Anthropic compatibility

Account

  • Authentication
  • Credits and billing
  • Limits
  • Errors
  • Security and data
  • FAQ

Account

Errors

The error shape, every code, and which ones to retry.

Errors use HTTP status codes and one JSON shape:

json
{
  "error": {
    "type": "invalid_request_error",
    "code": "TOOL_DEFINITION_INVALID",
    "message": "one or more tool definitions are invalid",
    "retryable": false,
    "request_id": "req_01jc8w7k2m4p6r8t0v2x",
    "details": [
      { "tool": "#3", "code": "INVALID_NAME", "path": "/function/name", "severity": "error", "message": "name must match ^[A-Za-z0-9_-]{1,64}$" }
    ]
  }
}

Branch on code, not on message; messages can be reworded. retryable tells you whether the same request might succeed later. request_id matches the X-Request-Id header.

#Codes

StatusCodeMeaningRetry?
400INVALID_REQUESTA field is missing or malformed. message says which.No
400UNKNOWN_TOOL_CHOICEtool_choice names a tool that isn't in the toolset.No
401INVALID_API_KEYMissing, malformed, wrong or revoked key.No
402INSUFFICIENT_CREDITSNot enough credits. Top up.After topping up
403FORBIDDENThe key can't do this.No
403TREE_SLOT_LIMIT_EXCEEDEDLegacy: toolsets are now unlimited.No
403FREE_TIER_TOOL_LIMIT_EXCEEDEDMore than 20 tools on the Free plan.No
403FREE_TIER_EDIT_NOT_ALLOWEDFree can't add versions to a toolset.No
404BRICK_NOT_FOUNDNo toolset with that id in your account.No
404VERSION_NOT_FOUND, JOB_NOT_FOUNDNo such version or build job.No
409BRICK_NOT_READYThe toolset has no ready version yet.Yes, after the build
409BRICK_NAME_CONFLICTYou already have a toolset with that name.No
409VERSION_CONFLICTbase_version isn't the latest version.After re-reading
409ALIAS_CONFLICTexpected_row_version didn't match.After re-reading
409IDEMPOTENCY_CONFLICTThe Idempotency-Key was used with a different body.No
413PAYLOAD_TOO_LARGE, TOO_MANY_TOOLSOver 1 MiB, or over 10,000 tools.No
415UNSUPPORTED_MEDIA_TYPEMissing Content-Type: application/json.No
422TOOL_DEFINITION_INVALIDTools break the rules. details lists each problem.No
429RATE_LIMITEDOver your rate. Wait Retry-After seconds.Yes
502INVALID_ENGINE_OUTPUTAn internal step returned something unusable.Yes
503OVERLOADED, ENGINE_UNAVAILABLE and similarTemporarily unavailable. Honour Retry-After.Yes
504DEADLINE_EXCEEDEDThe request took too long.Yes
500INTERNALA bug on our side.Yes, once

#Retrying well

Retry only when retryable is true. Wait Retry-After seconds when it's set, otherwise back off exponentially from about half a second, and give up after a few tries. Send an Idempotency-Key with requests you retry, so a retry of a request that actually went through isn't charged twice.

#Problems inside a tool list

TOOL_DEFINITION_INVALID comes with details, one entry per problem. tool is the tool's name, or #3 (its position, from 1) when the name itself is the problem. path is a JSON pointer inside that tool. The builder in the console shows these next to the right field.

PreviousLimitsNext Security and data

Something unclear or missing? Write to [email protected] and we'll fix the page.

On this page

  • Codes
  • Retrying well
  • Problems inside a tool list