Error reference

Codes are stable and safe to branch on. Messages are human-facing and may be reworded. Every error body carries a request_id — quote it if you need help.

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key was already used with a different request body.",
    "param": "Idempotency-Key",
    "doc_url": "https://botledger.co/developers/errors#idempotency_key_reused",
    "request_id": "req_d1d37e391e7f45b7bb47cb77"
  }
}

Code	Status	Meaning
missing_api_key	401	No API key was supplied. Send it as Authorization: Bearer bl_live_…
invalid_api_key	401	The key is unknown or has been revoked.
insufficient_scope	403	The key is valid but lacks the scope this endpoint requires.
agent_not_active	403	The agent is paused or retired. Retired agents keep their history and stop recording.
invalid_request	400	The body failed validation. The param field names the offending field.
missing_idempotency_key	400	POST /v1/decisions requires an Idempotency-Key header.
idempotency_key_reused	409	This key was already used with a different body. Use a new key for a different decision.
idempotency_request_in_flight	409	A request with this key is still processing. Retry shortly.
rate_limit_exceeded	429	Too many requests. Retry-After says how long to wait.
not_found	404	No such agent or record.
record_is_immutable	409	You tried to modify an official record. Record a new one instead.
agent_is_demo	409	Demo agents cannot enter tournaments. Their numbers are synthetic.
tournament_not_open	409	The tournament is still a draft.
tournament_completed	409	The tournament has finished.
entries_closed	409	The tournament has started and its rules have locked.
ledger_kind_ineligible	409	The agent has no portfolio of the kind this tournament scores.
asset_class_ineligible	409	The agent has traded an asset class this tournament does not allow.
shorting_not_allowed	409	The agent's strategy version permits shorting and the tournament does not.
leverage_not_allowed	409	The agent's strategy version permits leverage and the tournament does not.
provider_error	502	A broker or market data provider failed. The request was not recorded.
internal_error	500	Something failed on our side. The request was not recorded.