错误处理

API 使用标准 HTTP 状态码。成功响应直接返回资源体。错误遵循 RFC 9457 Problem Details for HTTP APIs（application/problem+json），并带两个扩展成员：用于程序化判断的顶层 code，以及单字段校验错误上的顶层 field（snake_case）。当多个字段同时出错时，field 被 errors[] 数组替代（Paymos 扩展成员，§3.2），承载逐字段的明细。

{
  "type": "https://paymos.io/docs/errors/codes#insufficient_balance",
  "title": "Conflict",
  "status": 409,
  "detail": "Merchant balance is insufficient.",
  "code": "insufficient_balance"
}

每个错误响应都遵循 RFC 9457 Problem Details for HTTP APIs，以 Content-Type: application/problem+json 返回。

单错误（多数响应）

{
  "type": "https://paymos.io/docs/errors/codes#insufficient_balance",
  "title": "Conflict",
  "status": 409,
  "detail": "Merchant balance is insufficient.",
  "code": "insufficient_balance"
}

多字段校验

仅在多个字段同时校验失败时发出。顶层 code 恒为 validation_failed；逐字段明细在 errors[] 中：

{
  "type": "https://paymos.io/docs/errors/codes#validation_failed",
  "title": "Bad Request",
  "status": 400,
  "detail": "Validation failed.",
  "code": "validation_failed",
  "errors": [
    { "code": "field_required", "field": "currency", "message": "Currency is required." },
    { "code": "field_must_be_positive", "field": "amount", "message": "Amount must be > 0." }
  ]
}

字段参考

为什么要结构化错误码（而不只是 message）

message 和 detail 文本可能在版本之间演进、被本地化或补充上下文。code 是稳定的契约——一个错误码发布后，其语义永不改变。程序化判断和本地化都基于 code。

import { RateLimitError, ValidationError } from '@paymos/sdk';

try {
  await paymos.withdrawals.create(request);
} catch (error) {
  if (error instanceof ValidationError) {
    for (const item of error.errors) highlight(item.field, item.message);
  } else if (error instanceof RateLimitError) {
    scheduleRetry(error.retryAfterSeconds);
  }
  throw error;
}

use paymos::{ApiErrorKind, Error};

match paymos.withdrawals().create(&request).await {
    Ok(withdrawal) => process(withdrawal),
    Err(Error::Api(error)) if error.kind == ApiErrorKind::Validation => {
        for item in &error.errors {
            highlight(item.field.as_deref(), &item.message);
        }
    }
    Err(Error::Api(error)) if error.kind == ApiErrorKind::RateLimit => {
        schedule_retry(error.retry_after);
    }
    Err(error) => return Err(error),
}

错误类型

每个状态都随错误封装返回，带 title 和机器可读的 code。一个状态可能覆盖多种场景——按 code 分支，而不是按状态码。

客户端逻辑始终由 code（而非 HTTP 状态）驱动——多个不同的业务场景共用一个 HTTP 状态，线上错误码用来区分它们。

限流

API 默认允许每个商户每秒 30 次请求，POST /v1/invoices 有更严格的限制（5 次/秒）。限流按商户、按一秒窗口计数——你持有的每个 API 密钥共用同一份预算——两者都可按商户配置。超过限制时会收到 429 Too Many Requests 响应，并携带 Retry-After: 1 请求头。

{
  "type": "https://paymos.io/docs/errors/codes#rate_limited",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded (30 req/sec). Retry after 1 second.",
  "code": "rate_limited"
}