Error Codes

Applies to: PayPlus REST API v2.1 Last updated: March 2026

This page documents all error codes returned by the PayPlus REST API. Errors are returned as JSON objects in the error field of the response envelope. Use the code field to identify and handle specific error conditions programmatically.

HTTP Status Codes

HTTP Status	Meaning	Typical Cause
200 OK	Request succeeded	Used for synchronous operations that return data (GET requests; synchronous instant payment initiation)
201 Created	Resource created successfully	ACH payment initiated; webhook registered
202 Accepted	Request accepted for asynchronous processing	Wire transfer accepted (settlement via webhook); RfP sent; ACH batch submitted
400 Bad Request	Invalid request format or parameters	Missing required field, invalid field value, malformed JSON, invalid routing number
401 Unauthorized	Authentication failed or missing	Missing Authorization header, expired access token, invalid API key
403 Forbidden	Authenticated but not authorized	OAuth scope does not permit the requested operation; API client restricted from the specified rail
404 Not Found	Resource not found	Payment ID does not exist; return details requested for a payment that has not been returned
409 Conflict	Duplicate request conflict	Same idempotency key used with different request parameters
422 Unprocessable Entity	Business rule validation failed	Payment exceeds rail limit, SDA payment above $1M, effective date is not a business day
429 Too Many Requests	Rate limit exceeded	More than 120 requests per minute from the same API client
500 Internal Server Error	PayPlus internal error	Unexpected server error. Retry with exponential backoff. If persistent, contact PayPlus support with the `requestId`.
503 Service Unavailable	PayPlus temporarily unavailable	System maintenance or overload. Retry after the `Retry-After` header value (seconds).

Error Response Format

{
  "error": {
    "code": "INVALID_ROUTING_NUMBER",       // Machine-readable error code
    "message": "The routing number '099999999' is not a valid ABA routing number.",
    "field": "beneficiary.routingNumber",       // Field path (for validation errors)
    "details": {}                               // Additional context (not always present)
  },
  "meta": {
    "requestId": "req_9e7c4f2a1b3d",               // Include in support requests
    "timestamp": "2026-03-15T11:05:22Z"
  }
}

For validation errors affecting multiple fields, the response returns an array of errors:

{
  "errors": [
    { "code": "REQUIRED_FIELD_MISSING", "field": "originator.accountNumber", "message": "originator.accountNumber is required." },
    { "code": "INVALID_AMOUNT", "field": "amount", "message": "Amount must be a positive integer (cents). Received: -5000." }
  ],
  "meta": { "requestId": "req_9e7c4f2a1b3d", "timestamp": "2026-03-15T11:05:22Z" }
}

Validation Errors (400)

Code	Description	Resolution
`REQUIRED_FIELD_MISSING`	A required field is absent from the request body.	Check the `field` value in the error response. Add the missing field to the request.
`INVALID_FIELD_FORMAT`	A field value does not conform to the expected format.	Review the field specification in this documentation. Common causes: date not in YYYY-MM-DD format, currency code not ISO 4217.
`INVALID_ROUTING_NUMBER`	The provided ABA routing transit number is not a valid 9-digit ABA number or is not registered as an active ACH/Fedwire participant.	Verify the routing number against the Federal Reserve's E-Payments Routing Directory. Ensure no leading/trailing spaces in the string value.
`INVALID_BIC`	The provided BIC (Bank Identifier Code) is not a valid SWIFT BIC or is not active in the SWIFT BIC directory.	Verify the BIC is 8 or 11 characters. Check that the BIC is registered and active in the SWIFT BIC Plus directory.
`INVALID_AMOUNT`	Amount is not a positive integer, is zero, or exceeds the maximum value for the data type.	Amount must be a positive integer in cents (USD). Example: $1,500.00 = `150000`. Do not send decimal values.
`INVALID_SEC_CODE`	The provided NACHA SEC code is not recognized or is not enabled for this PayPlus instance.	Verify the SEC code is one of the supported values: PPD, CCD, CTX, WEB, TEL, IAT. Contact your PayPlus administrator if the SEC code should be supported but is not enabled.
`INVALID_CURRENCY`	The currency code is not a valid ISO 4217 three-letter code or is not supported by the target rail.	Fedwire only supports USD. SWIFT supports the currencies enabled in your SWIFT connector configuration.
`FIELD_TOO_LONG`	A string field exceeds the maximum allowed length.	Truncate the field value. The error message includes the maximum length for the field.
`INVALID_DATE`	A date field is not a valid calendar date, is not a business day, or is outside the allowed date range.	Verify the date is a valid business day in YYYY-MM-DD format. ACH effective dates must be today or a future business day. Fedwire does not support future value dates.

Authentication and Authorization Errors (401 / 403)

Code	HTTP	Description	Resolution
`MISSING_AUTHORIZATION`	401	No Authorization header or X-API-Key header provided.	Add the Authorization header: `Authorization: Bearer {access_token}` or `X-API-Key: {key}`.
`INVALID_TOKEN`	401	Access token is malformed, expired, or has been revoked.	Request a new access token via `POST /auth/token`.
`INVALID_API_KEY`	401	The provided API key is invalid or has been deactivated.	Verify the API key is correct and active in the PayPlus Admin Console.
`INSUFFICIENT_SCOPE`	403	The access token does not include the required OAuth scope for this operation.	Request a new token with the required scope. See the Authentication section for scope definitions.
`RAIL_ACCESS_DENIED`	403	This API client is not authorized to initiate payments on the requested rail.	Contact your PayPlus administrator to enable the required rail for this API client.
`AMOUNT_LIMIT_EXCEEDED`	403	The payment amount exceeds the limit configured for this API client or the originating account.	The per-transaction or daily limit for this client has been reached. Contact your PayPlus administrator to review limit configuration.

Payment Business Rule Errors (422)

Code	Description	Resolution
`RAIL_LIMIT_EXCEEDED`	Payment amount exceeds the maximum transaction limit for the requested rail.	Use a different rail or split into multiple payments. Fedwire has no enforced maximum; RTP limit is $1,000,000; FedNow default limit is $500,000.
`INSTANT_RAIL_NOT_AVAILABLE`	Neither RTP nor FedNow is available for the specified receiving bank routing number.	Verify the receiving bank's instant payment participation. Route to ACH or Fedwire as an alternative.
`SDA_NOT_ELIGIBLE`	The payment is not eligible for Same-Day ACH processing.	Common causes: amount exceeds $1,000,000 (SDA limit), IAT SEC code (not SDA eligible), submission received after the final SDA window cut-off. Use standard ACH processing.
`FEDWIRE_OUTSIDE_HOURS`	Fedwire wire transfer submitted outside Fedwire operating hours (Monday–Friday, 9:00 PM ET prior day to 6:30 PM ET).	The payment will be queued and submitted at the next Fedwire opening. No action required — the payment will proceed automatically. Subscribe to the `payment.submitted` webhook to confirm submission.
`TRAVEL_RULE_FIELDS_MISSING`	Payment meets the BSA Travel Rule threshold ($3,000+) but required originator or beneficiary address fields are missing.	Add complete address information (`street`, `city`, `state`, `postalCode`, `country`) for both originator and beneficiary.
`REVERSAL_WINDOW_EXPIRED`	ACH reversal request submitted more than 5 banking days after the original payment's settlement date.	The reversal window has passed. Contact the beneficiary bank directly to arrange a voluntary return.
`PAYMENT_NOT_REVERSIBLE`	Reversal requested for a payment that is not in a reversible state (e.g., already returned, rejected, or a debit entry type not eligible for reversal).	Review the payment status. Reversal is only available for settled credit entries within the 5-day window.
`DUPLICATE_IDEMPOTENCY_KEY`	The provided idempotency key was previously used with different request parameters.	Generate a new unique idempotency key (UUID v4) for each distinct payment request.

Rail-Specific Return Codes

ACH Return Codes

ACH return codes appear in the returnCode field of returned payments and in the payment.returned webhook event. See the Get Return Details endpoint for full return information.

Code	Reason	Representable
`R01`	Insufficient Funds	Yes — within 180 days per NACHA rules
`R02`	Account Closed	No
`R03`	No Account / Unable to Locate Account	No
`R04`	Invalid Account Number Structure	No
`R05`	Unauthorized Debit to Consumer Account (CCD/CTX) — potential regulatory issue	No — investigate authorization
`R07`	Authorization Revoked by Consumer (PPD/TEL/WEB)	No
`R08`	Payment Stopped	No
`R10`	Customer Advises Not Authorized — Reg E dispute	No — potential Reg E violation; review
`R16`	Account Frozen — regulatory or legal hold	No
`R20`	Non-Transaction Account — savings/money market debit limit exceeded	Contact RDFI
`R29`	Corporate Customer Advises Not Authorized (CCD/CTX/PPD)	No — investigate authorization

Instant Payment Return Codes (RTP / FedNow)

ISO 20022 reason codes returned in the pacs.002 rejection/return message from the Receiving Bank:

Code	Reason
`AC01`	Incorrect Account Number — account number is invalid
`AC04`	Closed Account Number — account no longer exists
`AC06`	Blocked Account — account is frozen due to regulatory or court order
`AG01`	Transaction Forbidden — transaction type not permitted for this account
`AM04`	Insufficient Funds — not used by RTP/FedNow (payment accepted regardless of receiver balance); returned only for settlement account issues
`NARR`	Narrative — Receiving Bank returned with a free-text explanation. See `returnNarrative` field.
`RR04`	Regulatory Reason — payment blocked for regulatory compliance by Receiving Bank

Compliance Errors

Code	HTTP	Description
`OFAC_MATCH`	202	Payment accepted but placed on compliance hold due to OFAC SDN list match. The payment will not be submitted to the network until the hold is resolved by a Compliance Officer. Subscribe to `compliance.hold` and `compliance.released` / `compliance.rejected` webhook events.
`OFAC_SCREENING_ERROR`	503	OFAC screening engine is unavailable. Payment placed on hold. PayPlus will retry screening automatically when the screening engine recovers. The `compliance.hold` webhook event will fire; the payment will proceed when cleared.
`SANCTIONED_COUNTRY`	422	Payment destination country or beneficiary bank country is subject to a comprehensive OFAC sanctions program. Payment cannot be processed. Do not retry — contact your Compliance team.

Handling OFAC Holds in Your Integration If your integration uses instant payments for time-sensitive use cases, subscribe to both compliance.hold and compliance.released webhooks. When a payment enters compliance hold, notify the payment initiator that the payment is under review. When the hold is released, the payment proceeds automatically — no resubmission required.

← Webhooks Back to Overview →