오류와 멱등성

하나의 오류 응답 구조, 안정적인 코드, 그리고 실제로 돈을 지켜주는 멱등성.

아직 사용할 수 없습니다 — api.baynoy.com 도메인이 조회되지 않으므로 아래 예제는 지금 실행되지 않습니다. 저희가 만들어 가는 계약을 설명한 것이며, 이 페이지의 형식은 아직 바뀔 수 있습니다.

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.