错误与幂等性
统一的错误封装、稳定的错误码,以及真正能守住资金的幂等性。
尚未上线 —— 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 conflictRetries 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.