Errors & idempotency

One error envelope, stable codes, and idempotency that actually protects money.

Not live yet — api.baynoy.com does not resolve, so the examples below will not run today. They describe the contract we are building to, and the shapes on this page may still change.

One error envelope

Every non-2xx response carries {"error": {"code", "message", "details?"}}. Branch on code. Never branch on message: messages are for humans and they change.

Node
const res = await fetch(url, init);
if (!res.ok) {
  const { error } = await res.json();
  switch (error.code) {
    case "insufficient_funds": return showTopUp();
    case "rate_limited":       return retryLater();
    default: throw new Error(`${error.code}: ${error.message}`); // unknown codes are bugs, not flows
  }
}

Idempotency is not optional on money

Send an Idempotency-Key on every POST that moves money. The same key with the same body returns the first result; the same key with a different body is a conflict. Generate the key before the first attempt and reuse it for every retry of that same intent.

cURL
curl https://api.baynoy.com/v1/payouts \
  -H "Authorization: Bearer bk_test_..." \
  -H "Idempotency-Key: 7c1f0b6e-..." \
  -H "Baynoy-Signature: kid=key_...,ts=1794300000,nonce=8f2c...,v1=<hex>" \
  -H "Content-Type: application/json" \
  -d '{"beneficiaryId": "ben_123", "amountMinor": "250000", "assetKey": "fiat:EUR"}'

# same key + same body  -> the original result, no second payout
# same key + other body -> 409 conflict

Retries and rate limits

Retry 5xx and rate_limited with exponential backoff and jitter; never retry a 4xx other than rate_limited without changing something. Rate-limit responses carry the wait time in details — respect it rather than guessing.