Error codes and HTTP status

Summary

1. The HTTP status tells you whether the request was executed. A 4xx means the request was rejected and had no business effect (a 409 means a related object already exists). A 2xx means it was processed.
2. The business result is in the object's status. A 2xx doesn't mean the charge succeeded. A payment has succeeded only when status=succeeded, or when you receive a payment.succeeded event whose signature you've verified.
3. A 5xx or a timeout means "outcome unknown". The request may already have been accepted. Retry with the original idempotency key, or query by merchant order ID, and never charge again with a new key (the exception is 503 temporarily_unavailable, where this request wasn't accepted).

HTTP status

• A network timeout, a dropped connection or no response at all is handled like a 5xx: the outcome is unknown.
• 503 temporarily_unavailable is the only 5xx that clearly means "not accepted": the platform has paused new transactions on this channel, so this request wasn't executed and created no payment or charge. Retry later with the original idempotency key. The response doesn't give the internal reason. Treat every other 5xx as an unknown outcome.
• A 5xx response may not be JSON (for example, HTML returned by a gateway). If you can't parse it, treat it as "outcome unknown" too.
• Once the platform has accepted a payment, it never disguises a provider timeout as a 429. An accepted request returns 202 processing.

Error response structure

{
  "error": {
    "code": "payment_in_progress",
    "message": "This order already has an unfinished payment attempt. Check the result of the original payment.",
    "field": null,
    "related_resource_id": "pay_demo_001",
    "retryable": false
  },
  "request_id": "req_demo_error"
}

What retryable means

1. retryable=true only means "it's appropriate to resend the same request with the original idempotency key", as with rate_limited, operation_in_progress, internal_error and temporarily_unavailable.
2. It doesn't authorize you to switch to a new idempotency key or a new merchant order ID, or to "create another payment". When the outcome is unknown, retrying with a new key can cause a duplicate charge.
3. retryable=false doesn't mean "this payment failed". For example, payment_in_progress is false because the right move is to retrieve the existing payment, not to resend the request.
4. When the provider clearly declines the charge, the API doesn't return an error. It returns the payment with status=failed and a failure object. See Payment failure reasons versus API errors.

Error code reference

Program against error.code, and tolerate error codes that are added in the future (handle them by HTTP status). You can link directly to any row with #code-<error_code>, for example #code-payment_in_progress.

Errors by endpoint

Every endpoint can return unauthenticated (401), forbidden (403), rate_limited (429), internal_error (500) and upstream_unavailable (502 / 503). Endpoints that take parameters or a request body can also return invalid_request (400). temporarily_unavailable (503) is returned only by the endpoints that start new transactions: createPayment, confirmPayment and createCheckoutSession. The table below lists only the error codes specific to each endpoint:

Payment failure reasons versus API errors

failed is not a terminal state. After you receive payment.failed, the payer can still retry and succeed, so process events by version. When 3DS authentication succeeds but the issuer declines the charge, the payment is failed with a failure object. That isn't an API error.

Failure reason codes

Payment failure reasons

These are mapped from the provider's result. Your client must tolerate unknown failure.code values and treat them as a failed payment, prompting the payer to use another card.

When the payer closes the authentication page, the platform doesn't infer a result, so no failure reason appears right away. A reason such as authentication_expired appears only after the provider confirms that no charge was made.

Refund failure reasons

These appear only when a refund is failed or rejected:

Handling example

The functions below classify the result of a call into "what to do next". Unknown error codes fall into the default branch and are handled by HTTP status.

const API_BASE = 'https://api.payhub.example';

// Return "what to do next"; unknown error codes are handled by HTTP status
export async function callPayHub(method, path, { body, idempotencyKey } = {}) {
  let res;
  try {
    res = await fetch(`${API_BASE}${path}`, {
      method,
      headers: {
        Authorization: `Bearer ${process.env.PAYHUB_API_KEY}`,
        ...(body ? { 'Content-Type': 'application/json' } : {}),
        ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {})
      },
      body: body ? JSON.stringify(body) : undefined,
      signal: AbortSignal.timeout(20_000)
    });
  } catch (cause) {
    return { next: 'unknown', cause }; // Timeout or network error: outcome unknown, so retry with the same key or query by order ID
  }
  const data = await res.json().catch(() => null); // A 5xx response may not be JSON
  const requestId = data?.request_id;
  if (res.ok) return { next: 'check_status', httpStatus: res.status, data, requestId };
  if (res.status === 429) {
    const raw = res.headers.get('Retry-After');
    const after = raw === null ? NaN : Number(raw);
    return { next: 'retry_same_key', afterSeconds: Number.isFinite(after) ? after : 1, requestId };
  }
  if (res.status >= 500) {
    // 503 temporarily_unavailable: not accepted, so retry later with the original idempotency key; any other 5xx: outcome unknown
    if (data?.error?.code === 'temporarily_unavailable')
      return { next: 'retry_same_key_later', requestId };
    return { next: 'unknown', requestId };
  }
  const error = data?.error ?? {};
  switch (error.code) {
    case 'payment_in_progress':
    case 'order_no_conflict':
    case 'refund_no_conflict':
      return { next: 'query_existing', id: error.related_resource_id, requestId };
    case 'operation_in_progress':
      return { next: 'retry_same_key', afterSeconds: 2, requestId };
    case 'idempotency_conflict':
      return { next: 'fix_integration', requestId }; // Same key, different parameters: fix key generation and alert
    default:
      return {
        next: 'rejected',
        httpStatus: res.status,
        code: error.code,
        field: error.field,
        message: error.message,
        requestId
      };
  }
}

Contact support

• First, look up the call in the merchant portal by request_id. The record shows the method, path, duration, HTTP status and a sanitized error summary: API call logs (opens the merchant portal in a new tab) (Requires Owner, Admin or Developer).
• When you contact support, include the request_id, the time it happened (with time zone), the environment (test / live), the endpoint, and the merchant order ID or the platform object ID.
• Never send an API key, a webhook signing secret, a full card number, a CVC, or an authentication or checkout link that contains a token.