Skip to main content
This page covers everything you need to handle errors gracefully: HTTP codes, commit statuses, signature debugging, and health monitoring.

HTTP Status Codes

If you’re seeing an unexpected error, join our Discord and the team will help you debug it.

Commit Status

The /commit endpoint returns a status field rather than an HTTP error for action-level outcomes. Always check this field after committing.
A rejected, failed, or expired status still means the commit succeeded. The balance is no longer in a pending state. No further action is required.

Idempotency

/commit is idempotent. If you call it twice with the same tx_id, the second call returns already_processed: true and the same status as the first call. This is safe - use it to confirm commit state after a crash or retry.

Recovering Pending Commits

If a transaction is submitted but /commit is never called - due to a crash, timeout, or network issue - the user’s balance remains in a pending state. Use POST /account/pending on startup to detect and recover these states:

Handling 401 - Signature Errors

The most common cause of a 401 on signed endpoints is a malformed signature message. Check:
  1. Message format - the ToS header line and Details: line must match exactly, including the newlines.
  2. Timestamp - must be Unix time in milliseconds, not seconds. Stale timestamps are rejected.
  3. Signing key - must be the Ed25519 secret key of user_address, not any other key.
  4. Encoding - the signature must be base64-encoded, not base58 or hex.
The most common mistake is passing seconds instead of milliseconds for the timestamp. Use Date.now() in TypeScript or timestamp_millis() in Rust - not Date.now() / 1000 or timestamp().

Health Check

Use GET /health to verify API availability or plug it into your monitoring stack for uptime alerts. It requires no signed request - just your API key.

Experiencing an issue not covered here? Join us on Discord - our engineers are available to help.