---
title: 错误码
description: Coinetic 加密支付 API 错误码参考：每个错误码的含义与处理方法，涵盖请求签名、幂等性、账单、可支付资产、退款和频率限制，帮助您快速排查集成问题。
url: https://coinetic.money/zh/docs/errors/
lang: zh-Hans
---

# 错误码

错误响应体的结构始终相同。请以 `code` 为准，而不是文本：文本是写给人看的，可能会变化。

```json
{ "error": { "code": "duplicate_order", "message": "该 order_id 的账单已创建" } }
```

> **何时可以安全重试.** 遇到 `429`、`500`、`503`、`idempotency_in_progress` 以及网络错误时，**使用相同的 `Idempotency-Key`** 重试：不会产生重复。

## 请求与访问

| HTTP | code | 原因及处理方法 |
| --- | --- | --- |
| 400 | `bad_json`、`bad_body` | 请求体不是 JSON、包含多余字段，或金额用了数字而非字符串：请修正请求 |
| 400 | `bad_idempotency_key` | 缺少幂等键或格式错误：需为 8–128 个可打印 ASCII 字符，且不能以 `d:` 开头 |
| 400 | `bad_query` | 列表参数无效 |
| 401 | `unauthorized` | 签名、时间、nonce 或密钥有误：参见 [CP-HMAC](https://coinetic.money/zh/docs/authentication/) |
| 403 | `merchant_suspended` | 商户已被暂停：请联系客服 |
| 403 | `merchant_not_approved` | 接入尚未完成或申请正在审核中：请在后台完成接入向导 |
| 403 | `billing_suspended` | 平台手续费账单未支付：请在后台「计费」中支付，暂停将立即解除 |
| 404 | `not_found` | 账单不存在或不属于您 |
| 413 | `body_too_large` | 请求体超出限制：请精简 `metadata` |
| 429 | `rate_limited` | 请求过多：请以指数退避方式重试 |
| 500 | `internal` | 内部错误：请使用相同的 `Idempotency-Key` 重试 |

## 账单与幂等性

| HTTP | code | 原因及处理方法 |
| --- | --- | --- |
| 409 | `duplicate_order` | `order_id` 已被使用：请换一个新的，例如 `ORDER-1001-2` |
| 409 | `idempotency_conflict` | 相同的幂等键搭配了不同的请求体 |
| 409 | `idempotency_in_progress` | 首次请求仍在处理中：1–2 秒后重试 |
| 409 | `invoice_not_payable` | 账单已过期或已关闭：请创建新账单 |
| 422 | `invalid_order_id`、`invalid_price_amount`、`invalid_price_currency`、`invalid_return_url`、`invalid_expires_in_seconds`、`invalid_metadata` | 字段未通过校验：错误文本会提示具体规则 |
| 422 | `invalid_allowed_assets` | 列表中没有任何可用资产：错误文本会逐一说明原因 |
| 422 | `no_assets` | 没有任何可用资产：请在后台检查钱包和资产设置 |
| 422 | `amount_too_small` | 金额低于所有可用资产的最低金额 |

## 在支付页面选择币种

这些错误由支付页面处理：只有当您自己调用 `select` 时，您的服务器才会遇到它们。

| HTTP | code | 原因 |
| --- | --- | --- |
| 409 | `asset_locked` | 付款后尝试更换币种 |
| 409 | `wallet_not_configured` | 该网络没有有效的收款钱包 |
| 409 | `wallet_changed`、`address_conflict` | 请重新选择 |
| 422 | `asset_not_allowed` | 该资产不在账单中，或已不再允许 |
| 503 | `rate_unavailable` | 暂无经确认的汇率：请建议顾客使用稳定币 |
| 503 | `network_unavailable` | 该网络暂时无法收款：请选择其他网络 |

## 退款

| HTTP | code | 原因 |
| --- | --- | --- |
| 403 | `merchant_inactive` | 商店已被暂停或密钥已被吊销 |
| 409 | `invoice_not_paid` | 账单未选择资产：没有可退的款项 |
| 409 | `nothing_to_refund` | 款项已全部退还或已申请退款 |
| 409 | `too_many_refunds` | 该账单已有 20 个未完成的退款申请 |
| 409 | `refund_executor` | 该退款由平台执行，而不是由您执行 |
| 409 | `invoice_status_changed` | 提交申请后账单状态发生了变化：请带上 `"ack_status_change": true` 重试 |
| 422 | `amount_exceeds_refundable` | 金额超出可退金额：请减少金额或使用 `"full"` |
| 422 | `invalid_amount`、`invalid_address`、`invalid_tx_hash` | 字段未通过校验 |