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. |
| 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. |