跳转到主内容

引用错误

全部人员 API 错误返回 a JSON 带有 errors 数组。每个元素都携带 a detail 字符串和一些端点上的机器可读 code验证 失败列出每个字段的一个元素 。

规范定义是: §10 协议规格.

作为成功而出现的错误​

追索、限制和反欺诈不拒绝支付 HTTP 错误。它们创建 交易并标记它 rejected,所以反应是 201 Created 与一个完全普通的 机构 :

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "rejected",
  "error_description": "terminal not found"
}

代码只检查状态代码 记录未付订单的支付。 读取 status 每页 反应。 rejected 和 failed 意思是没有转移钱; charged 是唯一的解决结果。

错误响应格式​

{
  "errors": [
    { "code": "flow_not_continuable", "detail": "status_poll" }
  ]
}

几个结束点在此格式之前用QQ"error"回答:"......","message": 接受两种形状

HTTP 状态代码​

代码含义共同事业
400错误请求格式错误 JSON,缺少所需字段——在某些端点上,缺少 x-organization-id 页眉
401未经授权证书遗失或无效

处理 400 和 401 当它们不带字段指针时同样如此: 都意味着请求是 没有认证,而你得到哪一个取决于终点。 | 403 | 禁止 | 有效凭据但不允许使用此资源 | | 404 | 未找到 | 与给定的交易或资源 ID 不存在 | | 409 | 冲突 | 交易不能按要求从当前状态移动 | | 422 | 无法处理的实体 | 验证失败—— 1 errors 每个字段的元素 | | 429 | 请求过多 | 超过的费率限额 | | 500 | 内部服务器错误 | 平台错误——与交易的联系支持 ID |

交易错误代码​

这些都出现在 error_description 在网络记录有效载荷和交易情况反应中:

代码含义建议采取的行动
insufficient_funds贺卡下降:资金不足叫付款人用另一张卡
card_declined发卡人拒绝发卡叫付款人联系银行
expired_card纸牌过期日期已过要求付款人更新卡片细节
invalid_card_number纸牌号码无效检查牌号格式
invalid_cvvCVV 错误请付款人重新入境 CVV
do_not_honour银行普遍衰退叫付款人联系银行
lost_card报失的卡片不重试
stolen_card举报的卡片被盗不重试
restricted_card此交易不能使用卡片叫付款人用另一张卡
transaction_limit_exceeded超过贺卡/账户限额的数额要求付款人使用另一种付款方法
3ds_failed3D 安全认证失败要求付款人重试或使用另一张卡片
3ds_timeout3D Secure 验证超时重试交易
provider_unavailable暂时无法提供付款服务延迟后重试
routing_failed未找到此交易的提供者联系您的平台操作员
duplicate_txidtxid 已存在此终端使用一个独特的 txid 每笔交易
currency_not_supported此终端不支持的货币检查终端配置
amount_too_low该提供者低于最低数额增加交易额
amount_too_high该提供者超出上限的数额拆分为较小的交易
antifraud_reject受到反欺诈规则的阻碍联系您的平台操作员

校验错误( E)422)​

校验错误列表 1 errors 每个问题,每个问题都有 detail 命名字段的字符串 :

{
  "errors": [
    { "detail": "amount: can't be blank" },
    { "detail": "currency: is invalid" }
  ]
}

处理代码中的错误​

重试策略​

错误类型重试?说明
provider_unavailable曰对.单单 30–60 秒, 最大数 3 复试
3ds_timeout曰对.立即重试一次
insufficient_funds❌ No显示替代支付方法
card_declined❌ No显示替代支付方法
lost_card, stolen_card永远不要不重试或重现
duplicate_txid❌ No生成新的独有性 txid
routing_failed❌ No联系您的平台操作员

实例错误处理( Python)​

import requests

response = requests.post(
    'https://4pay.online/api/v1/transactions',
    headers={
        'x-api-key': 'YOUR_API_KEY',
        'x-organization-id': '00000000-1111-2222-3333-444444444444',
        'Content-Type': 'application/json',
    },
    json={'params': {'type': 'payment', 'amount': '1000', 'currency': 'USD',
                     'txid': 'order-1', 'env': 'prod'}}
)

if response.status_code == 422:
    for err in response.json().get('errors', []):
        print(err.get('detail'))
elif response.status_code == 409:
    print("The transaction cannot move as requested from its current state")
elif response.status_code >= 500:
    print("Platform error — retry later or contact support")
else:
    tx = response.json()
    print(f"Transaction created: {tx['id']}")

联系支助​

长期错误或意外 500 答复,联系人:

  • 电子邮件 : 支助@4pay.online
  • 包含交易 id (UUID用于更快的诊断