Errors

Payment Labs uses HTTP status codes to say what kind of failure happened, and a code in the body to say exactly which one. This page explains both and tells you what to do with each.

Before you start

You should be able to call the API with a token. See Environments and Authentication.

The error body

Most errors return a JSON object with two fields:

{
  "code": "NOT_EDITABLE",
  "message": "Payment P-01JBX7S9QK3M8T2N6R4W0Y5ZDE is not in draft or failed status."
}

• code: a machine-readable error code. Branch on it.
• message: a human-readable explanation. Log it, show it to an operator, never parse it. Its wording can change.

Handle the status code first, then the code when there is one. A few responses carry only message (for example some 409 responses), and a few come from the gateway as {"message": "Unauthorized"}. Your client must not fail when code is absent.

Validation errors

When one or more fields are missing or invalid, the response is 400 with code VALIDATION_ERROR and a details object. Each key is a field name (a dotted path for nested fields, such as buyer.email), and each value is the list of rules that field broke:

{
  "code": "VALIDATION_ERROR",
  "message": "There have been validation errors",
  "details": {
    "sourceAmount": [
      { "valid": false, "fieldName": "sourceAmount", "code": "MISSING_REQUIRED_FIELD", "message": "Field is required" }
    ],
    "nickname": [
      { "valid": false, "fieldName": "nickname", "code": "NOT_ALLOWED_FIELD", "message": "Field is not allowed" }
    ]
  }
}

Common rule codes:

Fix every field listed in details before you send the request again. Sending the same body again returns the same error.

Status codes

409 versus 423: both mean "not now". 409 usually means another request already did the thing, or a value clashes with an existing record. 423 means the object's state does not allow the change. In both cases, read the object before doing anything else.

Errors that need action outside the API

Each operation's reference page lists the codes specific to it.

Search errors

Search operations return 400 with a validation details entry for an invalid filter (for example INVALID_FIELD_NOT_ALLOWED when you filter on a field the operation does not support), and 400 INVALID_REQUEST when the search itself fails. See Search, Exports and Pagination.

Retrying safely

1. Retry only 401 (once, with a new token), 429, 500, 503 and network timeouts.
2. Wait before each retry and double the wait each time, starting at 1 second, with a small random jitter. Stop after 5 attempts.
3. Before retrying an operation that creates something (a batch, a payment, a checkout, a refund), check whether the first attempt succeeded. Most create operations are not idempotent. See Idempotency and Retries.

async function withRetry<T>(call: () => Promise<Response>, parse: (r: Response) => Promise<T>): Promise<T> {
  const retryable = new Set([429, 500, 502, 503, 504]);
  for (let attempt = 0; ; attempt++) {
    const response = await call();
    if (response.ok) return parse(response);
    if (!retryable.has(response.status) || attempt === 4) {
      const body = await response.text();
      throw new Error(`HTTP ${response.status}: ${body}`);
    }
    const delayMs = 1000 * 2 ** attempt + Math.random() * 250;
    await new Promise((resolve) => setTimeout(resolve, delayMs));
  }
}

Rate limits

Payment Labs does not publish per-account request quotas. If you receive 429 Too Many Requests, slow down and retry with the backoff above. Spread large jobs over time instead of sending them in parallel bursts, and use bulk operations and search instead of one request per object.

Next steps

• Idempotency and Retries
• Search, Exports and Pagination