Skip to content
HeartBadge docs

Error Codes

The full catalog of API error codes, what causes them, and how to handle each.

Every error response includes a stable error code, a human-readable message, and a correlation ID. This page is the catalog — one entry per code, with the conditions that produce it and the appropriate response.

This page is being written.

The structure is fixed. The prose is being drafted from the source material and reviewed by HeartChain Labs before publication. If you need this information urgently, email docs@heartbadge.com .

What this page will cover

  • Error response structure (code, message, correlation_id)
  • Auth errors (invalid signature, missing scope, revoked key)
  • Validation errors (missing fields, out-of-range values)
  • Business errors (insufficient balance, already redeemed)
  • Infra errors (rate limit, timeout, chain congestion)
  • Retry guidance per category