API Error Codes

When a request to the VoPay API fails, the response will include an ErrorCode and a Message describing the issue. Error codes are grouped by category:

Range	Category
`1xxx`	Authentication
`2xxx`	Validation
`3xxx`	Permissions
`9xxx`	Internal

Authentication Errors

Error Code	Description	Recommended Action
`1000` — Auth Failed	The API credentials provided are incorrect or invalid. Returned when the account key/password combination does not match, or when a token provided in the request is invalid or expired.	Double-check your `AccountID` and `Key` values. If using a token-based flow, ensure the token has not expired and was generated for the correct account.
`1001` — Incorrect Auth Type	The authentication method used is not supported. VoPay requires Basic Authentication on all requests.	Ensure your request includes a valid `AccountID` and `Key`. Other authentication schemes are not accepted.

Validation Errors

Error Code	Description	Recommended Action
`2000` — Missing Required Parameter	A required field was not included in the request body or query string.	Check the error message — it will identify the missing field. Refer to the endpoint's parameter reference to confirm all required fields are present.
`2001` — Invalid Parameter	A parameter was included but its value is not valid. Common causes include: malformed JSON, invalid date formats, a date range exceeding the allowed maximum, a transaction type mismatch, or a refund amount greater than the original transaction amount.	Review the value of the flagged parameter. Ensure dates are in `YYYY-MM-DD` format, numeric values are within allowed ranges, and the request body is valid JSON.
`2002` — Resource Not Found	The resource referenced in the request (e.g. account, bank account, transaction, webhook) does not exist.	Verify the ID or identifier used in the request is correct. If referencing a bank account or webhook, confirm it has been created before attempting to use it.
`2003` — Resource Already Exists	An attempt was made to create a resource that already exists (e.g. adding a user that is already linked to an account).	Check whether the resource already exists before attempting to create it. If you need to update an existing resource, use the appropriate update endpoint instead.
`2004` — Resource Inactive	The resource exists but is currently inactive.	Contact VoPay Support to investigate the status of the resource and reactivate it if appropriate.
`2005` — Invalid Action	The requested action cannot be performed in the current state or context. Common causes include: trying to activate an account that is already active, accessing a base endpoint directly without specifying a sub-endpoint, or attempting an operation on a resource that is not in the correct state.	Review the current state of the resource (e.g. account status, transaction status) and ensure the action is valid for that state. Check the error message for specifics.
`2006` — Invalid Transaction Status	The transaction is in a state that does not permit the requested operation. Common causes include: attempting to refund a transaction that still has a hold amount, or a transaction not being in the expected status for a refund or reversal.	Retrieve the transaction first to confirm its current status. Ensure any holds have cleared before attempting a refund, and that the transaction status matches what the operation requires.

Permission Errors

Error Code	Description	Recommended Action
`3000` — Permission Not Enabled	The requested feature or payment rail is not enabled for your account (e.g. EFT, ACH, Virtual Card).	Contact VoPay Support to request that the relevant feature or payment rail be enabled for your account.
`3001` — Transaction Limit Exceeded	The transaction amount exceeds the available balance or an account-level transaction limit.	Check the account's available balance before submitting transactions. If the limit is a configured daily or per-transaction cap, contact VoPay Support to review your limit settings.
`3002` — Invalid Access	The authenticated account does not have permission to access or modify the specified resource. This is returned when, for example, a bank account or transaction referenced in the request belongs to a different account.	Ensure the resource ID you are referencing belongs to your account. Sub-accounts can only access resources within their own scope.

Internal Errors

Error Code	Description	Recommended Action
`9996` — Endpoint Not Found	The requested API endpoint does not exist.	Verify the URL path is correct, including the version prefix (e.g. `/api/v2/`). Check for typos or incorrect HTTP methods.
`9997` — Integration Error	An error occurred while communicating with an external service (e.g. a banking partner or payment processor).	Retry the request after a short delay. If the error persists, contact VoPay Support with your request details and timestamp.
`9998` — Internal Error	An unexpected error occurred within VoPay's systems (e.g. a database operation failed).	Retry the request. If the issue persists, contact VoPay Support and include the full API response and the time of the request.
`9999` — Unknown Error	An unclassified error occurred.	Contact VoPay Support with the full error response and details of the request so the issue can be investigated.

Updated 1 day ago