Errors

All API errors return a consistent JSON body regardless of the HTTP status code. This document describes the shape, the error codes you may receive, and how to handle errors programmatically.

Error response format

{
  "message": "Human-readable description of what went wrong.",
  "error_code": "PAYMENT_ALREADY_REFUNDED"
}

Field	Type	Always present	Description
`message`	string	Yes	Human-readable explanation of the error.
`error_code`	string	Yes	Machine-readable code. Use this for programmatic error handling.

Correlation ID (request tracing)

Every response — success or error — includes an x-correlation-id header containing a unique ID for the request:

x-correlation-id: 9f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c

Log this value alongside every error. When contacting support, include the correlation ID and the Advance team can locate the full request trace immediately.

You can also supply your own correlation ID via the x-correlation-id request header and we'll echo it back:

POST /v1/plans
x-correlation-id: my-system-request-id-abc123

Bulk operation errors

When an operation fails because specific items are in an invalid state, a context object is included with the IDs of the affected items:

{
  "message": "Some payables can't be submitted — they must be in NEW or REVISION_REQUIRED status.",
  "error_code": "BAD_REQUEST",
  "context": {
    "invalid_ids": ["pay_aaa111", "pay_bbb222"]
  }
}

HTTP status codes

Status	Meaning
`200`	Success
`400`	Bad request — the request was invalid or the operation is not allowed
`401`	Unauthorized — missing or invalid API key
`403`	Forbidden — your API key does not have permission for this action
`404`	Not found — the requested resource does not exist
`422`	Unprocessable — validation failed or a database constraint was violated
`500`	Internal server error — something went wrong on our end

Error codes

Payment errors

`error_code`	Status	Description
`PAYMENT_ALREADY_REFUNDED`	400	The payment has already been fully refunded.
`PAYMENT_STATUS_NOT_REFUNDABLE`	400	Only Captured or Settled payments can be refunded.
`PAYMENT_MISSING_PAYRIX_TRANSACTION_ID`	400	The payment cannot be refunded through the API. Contact support.
`PAYMENT_REQUEST_EXPIRED`	400	The payment request has expired.
`PAYMENT_REQUEST_ALREADY_PAID`	400	This payment request has already been paid.
`PAYMENT_NOT_FOUND`	404	No payment found with the given ID.
`PAYMENT_REQUEST_NOT_FOUND`	404	No payment request found with the given ID.

Plan and invoice errors

`error_code`	Status	Description
`CHECKOUT_DETAILS_ALREADY_PAID`	400	This invoice has already been paid.
`CHECKOUT_DETAILS_EXPIRED`	400	This payment link has expired.
`CHECKOUT_DETAILS_CANCELLED`	400	This payment link has been cancelled.
`INVOICE_NOT_FOUND`	404	No invoice found with the given ID.

Resource errors

`error_code`	Status	Description
`NOT_FOUND`	404	Generic not-found for `HTTPException`-based routes.
`ITEM_NOT_FOUND`	404	A specific resource was not found.
`MISSING_REQUIRED_FIELDS`	400	The resource is missing required fields.
`BAD_REQUEST`	400	The request or operation is not valid.

Authentication and authorization errors

`error_code`	Status	Description
`UNAUTHORIZED`	401	Missing or invalid API key.
`FORBIDDEN`	403	The API key does not have permission for this resource or action.

Validation errors

`error_code`	Status	Description
`VALIDATION_ERROR`	422	Request body or query parameter failed validation.
`FOREIGN_KEY_VIOLATION`	422	A referenced resource (e.g., `insured_id`) does not exist.
`UNIQUE_CONSTRAINT_VIOLATION`	422	A record with these values already exists.

Server errors

`error_code`	Status	Description
`INTERNAL_SERVER_ERROR`	500	An unexpected error occurred. Include the `x-correlation-id` response header value in your support request.

Handling errors in code

Check `error_code` first

Never string-match on message — it may change. Use error_code for all programmatic decisions:

import requests

response = requests.post("/v1/payments/pay_xyz/refund", ...)

if not response.ok:
    error = response.json()
    code = error.get("error_code")

    if code == "PAYMENT_ALREADY_REFUNDED":
        # Payment was already refunded — treat as success
        pass
    elif code == "PAYMENT_STATUS_NOT_REFUNDABLE":
        # Notify user the payment status doesn't allow refunds
        raise ValueError(error["message"])
    else:
        # Unexpected error — log the x-correlation-id header for support
        ref = response.headers.get("x-correlation-id", "unavailable")
        raise RuntimeError(f"Refund failed [{code}]. Correlation ID: {ref}")

const response = await fetch('/v1/payments/pay_xyz/refund', { method: 'POST', ... });

if (!response.ok) {
  const error = await response.json();

  if (error.error_code === 'PAYMENT_ALREADY_REFUNDED') {
    // already done — no action needed
  } else {
    const ref = response.headers.get('x-correlation-id') ?? 'unavailable';
    console.error(`Error ${error.error_code}: ${error.message} (ref: ${ref})`);
    throw new Error(error.message);
  }
}

Bulk operations

When submitting multiple items and receiving a context.invalid_ids response, retry with only the valid subset:

error = response.json()
invalid = set(error.get("context", {}).get("invalid_ids", []))
valid_ids = [id for id in submitted_ids if id not in invalid]
# retry with valid_ids

Contacting support

Include the x-correlation-id response header value in your support request or API integration error logs. This is the single most useful piece of information for diagnosing issues.

Retry guidance

Status	Retry?
`400`	No — the request itself is invalid. Fix the request before retrying.
`401` / `403`	No — check your API key and permissions.
`404`	No — the resource does not exist.
`422`	No — validation or constraint failure. Fix the data.
`429`	Yes, with backoff — you are being rate limited.
`500`	Yes, with exponential backoff — transient server error. If it persists, contact support with the `x-correlation-id` header value.