Skip to main content

Documentation Index

Fetch the complete documentation index at: https://agent37.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Every error uses a standard HTTP status code and returns the same JSON body. Branch on code (it’s stable) and show message to a human.

​
Error body

Failed requests return an error object. code and message are always present; param and hint appear when they help. 
{
  "error": {
    "code": "insufficient_balance",
    "message": "Balance cannot cover a new instance.",
    "hint": "Add funds to your balance in the dashboard."
  }
}
​
error.code
string
A stable, machine-readable identifier. Branch on this, never on message or the HTTP status alone.
​
error.message
string
A human-readable description. Safe to show, but don’t parse it.
​
error.param
string
The request field that was invalid. Present on validation_error.
​
error.hint
string
A suggested next step, when one applies.

​
Codes

CodeHTTPMeaning
invalid_api_key401Missing, malformed, or revoked key.
insufficient_balance402Balance cannot cover this. Add funds to create instances or run managed calls.
instance_cap_reached402This instance hit its managed-usage cap. Raise managed_credit_cap_usd.
instance_not_found404No instance with that id on your account.
instance_not_running409The instance is not running. Wait for running, then retry.
session_busy409A response is already running on this session. Cancel first or use another.
insufficient_capacity503No room to provision right now. Safe to retry.
rate_limited429Too many requests. Retry after Retry-After.
validation_error400A request field was invalid. See param.

​
Handle them

Read code, then act. Billing codes (402) point your end user to the dashboard; 429 and 503 are retryable. 
const res = await fetch("https://api.agent37.com/v1/responses", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ instance_id: "inst_x7", input: "Draft a reply." }),
});

if (!res.ok) {
  const { error } = await res.json();
  switch (error.code) {
    case "session_busy":
      // a turn is already running: cancel it or open another session
      break;
    case "insufficient_balance":
    case "instance_cap_reached":
      // billing issue: send the user to the dashboard
      break;
    case "rate_limited":
    case "insufficient_capacity":
      // transient: back off and retry
      break;
    default:
      throw new Error(error.message);
  }
}
On 429, wait for the Retry-After header before retrying. insufficient_capacity (503) is also safe to retry with backoff.
insufficient_balance and instance_cap_reached are billing limits, not bugs. Balance and top-ups live in the dashboard. There is no balance API. See Billing for how managed spend is capped.

​
Notes per code

The Authorization header is missing, malformed, or the key was revoked. Send Authorization: Bearer sk_live_... and keep the key server-side. Rotate keys in the dashboard.
A session runs one response at a time. Sending new input while one is in flight returns this. Cancel the running turn with POST /v1/responses/{id}/cancel, or open another session.
A request field was invalid. Read param to find which one, then check the field against Send a message or Instances.

​
Next steps

Send a message

The core call, its fields, and the response shape.

Billing

Prepaid balance and per-instance managed-usage caps.

Streaming events

Render text, reasoning, and tool activity live.

Instances

Create, size, and manage the agent’s computer.