错误代码

所有 API 错误都返回相同的结构：

{
  "error": {
    "code": "payment_rejected",
    "message": "The selected currency is invalid.",
    "documentation_url": "https://app.so-amtar.com/docs/errors#payment_rejected"
  }
}

HTTP 状态码	含义
400	请求格式错误（请求头无效、JSON 无效）
401	认证失败（密钥缺失、无效或已撤销）
403	授权失败（权限不足）
404	该商户下找不到此资源
409	冲突（幂等不一致、请求处理中）
422	业务校验失败（超出限额、状态不一致）
429	请求频率超限
500	内部错误（请联系客服）
502	上游 Orange Money 不可用

完整列表

认证

• missing_credentials — 缺少 Authorization 请求头
• invalid_api_key — 密钥未知、已撤销或已过期，或 IP 不在允许列表中
• scope_insufficient — 密钥不具备该路由所需的权限

幂等性

• idempotency_key_too_long — 超过 255 个字符
• idempotency_conflict — 同一密钥对应不同的请求体，或请求仍在处理中

付款

• payment_rejected — 业务校验失败（服务商、币种、金额精度、限额、KYC）
• gateway_error — Orange Money 拒绝发起付款（502）
• transaction_not_found — 该商户下 id 或参考号未知（或创建于另一模式）

退款（POST/v1/refunds，scope can_refund）

• transaction_not_found (404) — 该商户下不存在此交易
• refunds_disabled (422) — 您的账户未启用退款
• refund_environment_mismatch (422) — 用测试密钥操作 live 交易，或反之
• transaction_not_refundable (422) — 交易状态不是 success
• non_payment_transaction_refund (422) — 只能对付款退款（不能对出款）
• provider_refund_unsupported (422) — 该支付渠道不支持退款
• refund_payer_phone_missing (422) — 付款缺少可退款的付款人号码
• amount_must_be_positive (422) — amount 必须大于零
• transaction_already_fully_refunded (422) — 该付款已全额退款
• refund_exceeds_refundable (422) — amount 超过剩余可退金额
• refund_rejected (422) — 因其他业务原因被拒绝
• scope_insufficient (403) — 密钥缺少 can_refund scope
• refund_not_found (404) — GET/v1/refunds/{id}：id 或参考号不存在

出款（payouts）

• payout_not_allowed_in_test_mode — 出款需要使用 live 密钥（sk_live_…）

分账（splits）

• split_rejected — 合计金额超过交易金额、收款方未激活，或交易已结束

处理建议

代码	建议操作
4xx（校验）	修正请求，并使用新的 Idempotency-Key
401	检查密钥。不要重试。
409	检查您的幂等逻辑
429	等待 Retry-After 后重试
5xx	使用相同的 Idempotency-Key 并按指数退避重试
502	上游 Orange Money 不可用：数秒后重试

报告错误

请发送邮件至 support@so-amtar.com，并注明：

• 错误代码
• documentation_url
• 准确的时间戳（UTC）
• 您的 merchant_ref 或 SOAMTAR id
• 响应中的 X-Request-Id 请求头（如有）