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_EXCEPTION`	400	The payment request has passed its `payment_expiration`.
`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_CANCELLED`	400	This plan has been cancelled. No payment is needed.
`CHECKOUT_DETAILS_SETTLED`	400	This invoice has been settled. No payment is needed.
`INVOICE_NOT_FOUND`	404	No invoice found with the given ID.
`PLAN_VERSION_CONFLICT`	409	Another edit to the plan was saved at the same time. Read the plan again and resend your edit.
`PLAN_NOT_EDITABLE`	409	The plan can no longer be edited, for example because it has received a payment. The message says why.
`PLAN_NOT_DELETABLE`	409	The plan can't be deleted because a payment was collected or its funds have already been moved. Cancel or refund it instead.
`PLAN_PAYOUTS_NOT_RECALCULATED`	422	The plan's payouts could not be recalculated, so the edit was not saved. Contact support.

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.

Payable errors

`error_code`	Status	Description
`PAYABLE_NOT_VOIDABLE`	409	The payable can't be voided in its current status (for example processing or paid).
`PAYABLE_GROUP_INCOMPLETE`	400	The payable belongs to an endorsement group and can't be approved on its own.

Money movement errors

`error_code`	Status	Description
`IDEMPOTENCY_KEY_REUSED`	422	The idempotency key was already used for a different request. Use a new key.
`IDEMPOTENCY_REQUEST_IN_PROGRESS`	409	A request with this idempotency key hasn't finished. Check the transfer's status before retrying.
`ACCOUNT_NOT_ELIGIBLE`	422	An internal transfer named an account that isn't one of your Advance accounts.
`recipient_not_found`	404	The market, producer or vendor doesn't exist.
`PAYOUTS_NOT_ENABLED`	400	The source account doesn't have payouts enabled.

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.