Errors

Every /api/v1 error has the same shape. Check the HTTP status first, then branch on error.code. The message text may change, so do not parse it. The exception is the position in a Beamline error, described below.

{
  "error": {
    "code": "invalid_chain",
    "message": "Unknown chain. Use one of: ethereum, base, bnb, arbitrum, optimism, polygon, solana.",
    "request_id": "req_342e0edcbc93"
  }
}

A successful response has data and meta at the top level, and an error response has error instead. No response has both.

#All codes

#Real samples

All samples on this page were captured on 2026-11-04 UTC.

#Bad parameter

GET /transfers?limit=500 returns 400.

{
  "error": {
    "code": "invalid_parameter",
    "message": "limit must be an integer from 1 to 100.",
    "request_id": "req_e79d46ca81d5"
  }
}

#Address on the wrong chain

GET /tokens/solana/0xdAC17F958D2ee523a2206206994597C13D831ec7 returns 400. The format is checked against the chain family.

{
  "error": {
    "code": "invalid_address",
    "message": "Not a valid Solana address.",
    "request_id": "req_dc305197db75"
  }
}

#Not found

not_found covers several cases. The message tells you which one. GET /labels/0x1111111111111111111111111111111111111111 returns this:

{
  "error": {
    "code": "not_found",
    "message": "This address is not in the Farbeam label set.",
    "request_id": "req_ebde8e2eae2b"
  }
}

A 404 on /labels/{address} is a normal result. It means the address has no label, and it says nothing about who owns it.

#Beamline parse error

POST /rules/validate with {"expression":"usd >= "} returns 422. The message ends with a zero-based character position. See Beamline errors.

{
  "error": {
    "code": "invalid_rule",
    "message": "Expected a value after \">=\" (at position 7)",
    "request_id": "req_27cf59c83919"
  }
}

#Refused webhook URL

POST /rules with http://example.com/x returns 422.

{
  "error": {
    "code": "invalid_url",
    "message": "url must use https",
    "request_id": "req_b53d936c174a"
  }
}

#Source failure

A 502 has one extra field, source. The name uses the source names listed on the status endpoint, such as rpc:ethereum:primary or defillama. The value token-report means every source behind a token report failed.

{
  "error": {
    "code": "upstream_unavailable",
    "message": "A public data source did not answer. Try again in a moment.",
    "source": "defillama",
    "request_id": "req_000000000000"
  }
}

Partial failure does not return 502. A wallet read with some failed chains returns 200 with partial: true. A token report with a failed source returns 200, its checks read unknown, and sources[].ok is false. See data sources.

#Handling code

body=$(curl -s -w "\n%{http_code}" "https://farbeamlabs.com/api/v1/chains/nope")
code=$(printf '%s' "$body" | tail -n1)
printf '%s' "$body" | sed '$d'
echo "HTTP $code"

const res = await fetch("https://farbeamlabs.com/api/v1/chains/nope");
const body = await res.json();
if (body.error) {
  const { code, message, request_id } = body.error;
  console.error(`${res.status} ${code}: ${message} (${request_id})`);
} else {
  console.log(body.data);
}

import requests

res = requests.get("https://farbeamlabs.com/api/v1/chains/nope", timeout=30)
body = res.json()
if "error" in body:
    e = body["error"]
    print(res.status_code, e["code"], e["message"], e["request_id"])
else:
    print(body["data"])

#Paths outside the API

The live stream at /api/live returns a bare 429 with retry-after: 30 and no JSON body when the stream limit is reached. Plan for that case in stream clients. See the streaming guide.