Errors

Ledgr uses standard HTTP status codes and returns one consistent error shape, so you can handle failures the same way everywhere. A 2xx status means the request succeeded. A 4xx means the request was rejected for a reason you can fix, such as a missing field or a state that does not allow the change. A 5xx means something failed on our side.

Every error looks like this:

{
  "status": "invalid_parameter",
  "message": "account.from and account.to must be different entities",
  "request_id": "9f2a1c84-6b0e-4a1f-9e2b-1d5c7a0e3f11",
  "request_time": "2026-08-07T19:12:04.221Z"
}

Branch your code on status, which is stable and machine-readable, rather than on message, which is written for people and may change. Log the request_id; it lets us trace the exact request if you need help.

Codes

status	HTTP	What it means
authentication_error	401	The API key is missing, invalid, or revoked.
invalid_request	400	The request was malformed, for example a missing body.
missing_parameters	400	A required parameter was left out.
invalid_parameter	400	A parameter was present but not valid.
not_found	404	The resource does not exist.
conflict	409	The request is not allowed from the resource's current state, such as an illegal status change.
insufficient_funds	422	The account does not have enough available balance.
rate_limit_exceeded	429	Too many requests. Slow down and retry.
not_implemented	501	The endpoint is not available yet.
internal_error	500	Something failed on our side. The message stays generic; use the request_id to investigate.

Handling failures well

Read the HTTP status first, then branch on status for anything you want to treat specially, such as showing an "insufficient balance" message to a user. A 4xx reflects the request itself, so fix or surface it. A 5xx is safe to retry, and if you retry with the same idempotency_key the operation is never applied twice.