Errors

Understand Payflow's response envelope, HTTP status codes, validation errors, authentication failures, and provider failures.

Payflow business endpoints return expected failures in the standard envelope:

{
  "success": false,
  "data": null,
  "message": "Readable error message"
}

Unexpected server errors hide internal details:

{
  "success": false,
  "data": null,
  "message": "Internal server error"
}

Status codes

Status	Meaning	Example
`400`	Invalid request body, query, signature, or field value.	Invalid payment request.
`401`	Missing, invalid, inactive, or expired API credential.	Invalid API credential.
`403`	Authenticated but not allowed.	ACH transfers require a secret key.
`404`	Resource does not exist in the caller's scope.	Application not found.
`409`	Business conflict or disabled capability.	Routing is not configured yet.
`422`	Provider or domain validation rejected the operation.	ACH transfer could not be created.
`428`	Password confirmation is required for a sensitive session action.	Password confirmation required.
`429`	Rate limit exceeded.	Rate limit exceeded.
`500`	Unexpected server failure.	Internal server error.
`502`	Upstream provider failed after Payflow prepared the operation.	Provider could not confirm payment.
`503`	Required infrastructure, authentication, Redis, or provider config is unavailable.	Dwolla ACH is not configured.

Validation errors are intentionally concise. They do not expose full Zod issue lists to public callers.

Example:

{
  "success": false,
  "data": null,
  "message": "Invalid payment request."
}

Use the endpoint reference to validate fields before sending requests.

Authentication can fail for several reasons:

Provider-facing operations can fail after Payflow validates the request. For example:

In customer-facing apps, prefer a calm generic message such as:

We could not start this payment. Please try again or use another method.

Keep the Payflow message, requestId, payflowReference, and provider reference in your internal logs.

Scenario	Retry?	Notes
Network timeout before response	Yes	Use the same idempotency key for ACH. For card flows, check whether a Payflow reference was created.
`400` validation error	No	Fix the request.
`401` or `403`	No	Fix credentials, permissions, origin, or environment access.
`409` routing or state conflict	No automatic retry	Operator action is usually required.
`429` rate limited	Yes, with backoff	Use exponential backoff and reduce request rate.
`502` or `503` provider unavailable	Yes, with backoff	Avoid tight loops; provider readiness work may be required.

Include a request ID in every server-side call:

X-Request-Id: checkout-order-1001-attempt-1

When contacting support or debugging internally, collect: