Payrix Pro API Error Handling Guide

Effective error handling is crucial for building robust and user-friendly integrations with the Payrix Pro API. This guide reviews common API errors and best practices for handling them, focusing on specific error use cases.

Errors returned by the Payrix Pro API are unique. Except for unauthorized requests or invalid syntax for a request, most errors return a 200 OK successful response (indicating successful communication with the server) with error-related metadata included in the errors array.

Error Format

The errors array metadata in every response describes any errors applicable to the request and features parameters that identify the nature of the error and how to proceed.

JSON

{
    "response": {
        "data": [],
        "details": {
            "requestId": 1
        },
        "errors": [
            {
                "field": "username",
                "code": 15,
                "severity": 2,
                "msg": "This field is required to be set",
                "errorCode": "required_field"
            },
        ]
    }
}

field: Identifies the parameter causing the error, if applicable.
code: Indicates the category of error.
severity: Determines the seriousness of the error and the next steps to proceed.
msg: Provides a summary of what triggered the error.
errorCode: References the unique Payrix Pro API server error code.

Severity

The severity parameter determines the immediate impact the error has on your request.

1: Informative error message. The request was processed.
2: Error warning. Request processing might continue based on the specific error.
3: Error notice. The request was unable to complete processing.
4: Failure notice. The request has failed and was not processed.

Note

While handling the following errors, contact Support if the issue continues after taking these troubleshooting steps.

Error Codes

Each error provides a code, errorCode, and msg (message) fields with details about the nature of the error. See the following table for information about each Payrix Pro API error:

`code`	`errorCode`	`msg`
`1`	`invalid_type`	Invalid request Content-Type header
`2`	`required_confirm`	An email confirmation is required to create the resource
`3`	`invalid_confirm`	Invalid confirmation code
`4`	`invalid_auth`	Invalid user authentication
`5`	`invalid_request_type`	Invalid request type, such as `PATCH`
`6`	`unsuccessful_processing`	Should be used for unknown processing errors
`7`	`blocked_ip`	The user’s IP address is blacklisted
`8`	`invalid_ip`	The user’s IP address is invalid
`9`	`cannot_update_delete`	The record cannot be updated or deleted
`10`	`no_relation`	The model relationship does not exist
`11`	`no_authed_user`	There is no authenticated user
`12`	`record_already_exists`	A record already exists in the database
`13`	`resource_not_found`	The requested action or resource does not exist
`14`	`invalid_params`	Request type/action cannot be defined in the processor
`15`	`create_error`	The record could not be created
`16`	`update_error`	The record could not be updated
`17`	`delete_error`	The record could not be deleted
`18`	`query_error`	The record could not be found
`22`	`no_success`	The requested action could not be processed
`23`	`invalid_request_auth`	Invalid user authentication for the requested action
`24`	`too_much_nesting`	The request has more than 10 nested models
`25`	`max_parent_login`	The maximum number of parent logins reached
`26`	`model_nosave`	The record or parent model has a flag set to inactive or frozen
`27`	`bad_response`	Bad response from the integration platform
`28`	`no_data`	No data received from the integration platform
`29`	`no_platform_set`	There is no available integration platform to process the transaction
`30`	`no_such_key`	The generic key does not exist
`31`	`no_permission`	The user has no permission over the record
`32`	`invalid_xml`	Syntax error
`33`	`invalid_json`	Syntax error
`34`	`no_batch`	The batch could not be created or found
`35`	`no_default_credential`	No default credentials set for this merchant
`36`	`no_default_payment`	No default payment set for this transaction
`37`	`not_boarded`	The merchant had not yet boarded
`38`	`invalid_rest_request`	REST request is not allowed
`39`	`fraud_detected`	The processor has detected fraud in the transaction.
`40`	`possible_fraud`	The processor has detected possible fraud in the transaction.
`41`	`fraud_bad_auth`	Transaction authorization is invalid.
`42`	`fraud_exp_auth`	Transaction authorization has expired.
`43`	`fraud_multi_bad_auth`	Multiple bad authorizations on the same day
`44`	`fraud_capture_no_auth`	The merchant has a capture with no authorization
`45`	`fraud_lower_value_auth`	The merchant has a capture with no authorization
`46`	`fraud_refund_limit`	The refund amount is higher than the limit
`47`	`fraud_capture_limit`	The capture amount is higher than the limit
`48`	`fraud_inactive_merchant`	The merchant has been inactive for the past X days
`49`	`fraud_daily_use_limit`	The same payment has been used more than the limit on the same day
`50`	`fraud_weekly_use_limit`	The same payment has been used more than the limit in the past 7 days
`51`	`fraud_sale_increase_limit`	Sales have increased by more than 20% past the limit this month
`52`	`fraud_refund_sale_ratio`	Refund-to-sale ratio is greater than the limit
`53`	`fraud_daily_ip_failed_auth`	Refund-to-sale ratio is greater than the limit
`54`	`bad_totals`	Bad totals field in request
`55`	`unknown`	Unknown error
`56`	`search_depth`	Search has more than 10 nested relations
`57`	`invalid_auth_public_api`	Invalid user authentication for the requested action using a public API key
`58`	`invalid_auth_public_session`	Invalid user authentication for the requested action using a public Session key.
`59`	`duplicate_request`	Duplicate request token detected
`60`	`duplicate_request_missing_record`	Missing original record from duplicate request
`61`	`invalid_request`	Invalid request
`62`	`invalid_sso_id`	Invalid SSO ID in request
`63`	`missing_sso_provider`	Missing SSO Provider in request
`64`	`rate_limit_exceeded_temp_block`	Rate of requests exceeded - Temporary block implemented

Authentication Errors

See common authentication errors you might encounter in the following table, along with their corresponding troubleshooting steps:

`code`	`errorCode`	Troubleshooting
`4`	`invalid_auth`	Check your authentication credentials and re-authenticate.
`11`	`no_authed_user`	Authenticate before performing the request.
`23`	`invalid_request_auth`	Verify your authentication for the requested action and re-authenticate.
`31`	`no_permission`	You have no permission over the record.
`57`	`invalid_auth_public_api`	Verify your authentication for the requested action using a public API key and re-authenticate.
`58`	`invalid_auth_public_session`	Verify your authentication for the requested action using a public Session key and re-authenticate.

Fund Batching Errors

See common fund batching errors you might encounter in the following table, along with their corresponding troubleshooting steps:

`code`	`errorCode`	Troubleshooting
`34`	`no_batch`	The batch could not be created or found; consider retrying.

API Request Errors

See common API request errors you might encounter in the following table, along with their corresponding troubleshooting steps:

`code`	`errorCode`	Troubleshooting
`1`	`invalid_type`	Ensure your Content-Type header in the request is set correctly, typically to application/json.
`5`	`invalid_request_type`	Ensure the request method (GET, POST, PUT, DELETE) is appropriate for your action.
`24`	`too_much_nesting`	Your request has too many nested models; simplify the request.
`38`	`invalid_rest_request`	REST requests are not allowed; use an alternative method.
`56`	`search_depth`	Your search has more than 10 nested relations; simplify the request.
`61`	`invalid_request`	Validate your request and correct any errors.
`62`	`invalid_sso_id`	Validate the SSO ID in the request and correct any errors.
`63`	`missing_sso_provider`	The SSO Provider is missing in the request; add it.
`64`	`rate_limit_exceeded_temp_block`	The rate of requests has exceeded the limit; retry after the temporary block is lifted.

Confirmation Errors

See common login confirmation errors you might encounter in the following table, along with their corresponding troubleshooting steps:

`code`	`errorCode`	Troubleshooting
`2`	`required_confirm`	Check your email for a confirmation code and enter it.
`3`	`invalid_confirm`	Verify the confirmation code you entered and re-enter it if incorrect.

IP Address Errors

See common IP address errors you might encounter in the following table, along with their corresponding troubleshooting steps:

`code`	`errorCode`	Troubleshooting
`7`	`blocked_ip`	Your IP address is blacklisted; contact support for details.
`8`	`invalid_ip`	Validate your IP address format and correct it.

Resource Errors

See common API resource errors you might encounter in the following table, along with their corresponding troubleshooting steps:

`code`	`errorCode`	Troubleshooting
`9`	`cannot_update_delete`	Note that the record cannot be updated or deleted; consider alternative actions.
`10`	`no_relation`	Verify the resource relationships and ensure they exist.
`12`	`record_already_exists`	The record already exists; check for duplicates.
`13`	`resource_not_found`	The requested resource does not exist; verify your request.
`26`	`model_nosave`	The record is inactive or frozen; consider alternative actions.
`35`	`no_default_credential`	No default credentials are set for the merchant; set them.
`36`	`no_default_payment`	No default payment method is set for the transaction; set it.
`37`	`not_boarded`	The merchant is not yet boarded; complete the boarding process.

Processing Errors

See common processing errors you might encounter in the following table, along with their corresponding troubleshooting steps:

`code`	`errorCode`	Troubleshooting
`6`	`unsuccessful_processing`	Log the error for further investigation and note that an unknown processing error occurred
`15`	`create_error`	Log the error and note that the record could not be created.
`16`	`update_error`	Log the error and note that the record could not be updated.
`17`	`delete_error`	Log the error and note that the record could not be deleted.
`18`	`query_error`	The record could not be found; verify your query.
`22`	`no_success`	Note that the requested action could not be processed; consider retrying.
`27`	`bad_response`	Log the error and note a bad response from the integration platform.
`28`	`no_data`	No data was received from the integration platform; consider retrying.
`29`	`no_platform_set`	There is no available integration platform to process the transaction.
`54`	`bad_totals`	Validate the `totals` field in the request and correct any errors.
`55`	`unknown`	Log the error and note that an unknown error occurred.

Fraud Detection Errors

See common fraud detection errors you might encounter in the following table, along with their corresponding troubleshooting steps:

`code`	`errorCode`	Troubleshooting
`39`	`fraud_detected`	Fraud has been detected in the transaction.
`40`	`possible_fraud`	Possible fraud has been detected.
`41`	`fraud_bad_auth`	The transaction authorization is invalid; re-authenticate.
`42`	`fraud_exp_auth`	The transaction authorization has expired; re-authenticate.
`43`	`fraud_multi_bad_auth`	Multiple bad authorizations have occurred on the same day.
`44`	`fraud_capture_no_auth`	A capture has occurred with no authorization.
`45`	`fraud_lower_value_auth`	A capture has occurred with an authorization lower than the transaction total.
`46`	`fraud_refund_limit`	The refund amount is higher than the limit.
`47`	`fraud_capture_limit`	The capture amount is higher than the limit.
`48`	`fraud_inactive_merchant`	The merchant has been inactive for the past X days.
`49`	`fraud_daily_use_limit`	The same payment has been used more than the limit on the same day.
`50`	`fraud_weekly_use_limit`	The same payment has been used more than the limit in the past 7 days.
`51`	`fraud_sale_increase_limit`	Sales have increased by more than 20% past the limit this month.
`52`	`fraud_refund_sale_ratio`	The refund-to-sale ratio is greater than the limit.
`53`	`fraud_daily_ip_failed_auth`	The refund-to-sale ratio is greater than the limit.

Syntax Errors

See common syntax errors you might encounter in the following table, along with their corresponding troubleshooting steps:

`code`	`errorCode`	Troubleshooting
`32`	`invalid_xml`	Validate the XML syntax and correct any errors.
`33`	`invalid_json`	Validate the JSON syntax and correct any errors.

Duplicate Request Errors

See common duplicate request errors you might encounter in the following table, along with their corresponding troubleshooting steps:

`code`	`errorCode`	Troubleshooting
`59`	`duplicate_request`	A duplicate request token was detected; verify your request.
`60`	`duplicate_request_missing_record`	The original record from the duplicate request is missing; verify your request.