Revolv3 API Response Codes and Errors

This guide provides a detailed overview of all possible HTTP status codes returned by the Revolv3 API, including success responses, client errors, server errors, and infrastructure-related issues from Revolv3.

Success Response Codes

These codes indicate successful operations.

Status Code	Description
200 (OK)	Successful request with data returned in the response body.
204 (No Content)	Request successful, but no data to return (e.g., a successful deletion or update without content).

Error Response Codes

These codes signal issues with the request or server-side problems. Always check the response body for detailed error messages where applicable.

Status Code	Description
400 (Bad Request)	Invalid field, value, or data formatting submitted. Includes validation errors. See the example below for details.
404 (Not Found)	Requested resource not found (e.g., customer, subscription, or invoice).
422 (Unprocessable Entity)	The request was well-formed but could not be processed. Check the error message or contact Revolv3 Support.
429 (Too Many Requests)	Rate limit exceeded. Limits: 20 calls per second or 20,000 calls per 15 minutes. Wait and retry after the limit resets.
500 (Internal Server Error)	Unexpected server error. Contact Revolv3 support if this persists.
502 (Bad Gateway)	Revolv3 application is down or unreachable. Contact Revolv3 support if this persists.
503 (Service Unavailable)	The service is temporarily unavailable, possibly due to maintenance or overload. Retry after a short delay. Contact Revolv3 support if this persists.
504 (Gateway Timeout)	Request timed out while waiting for a response from the server. This could occur if the API call exceeds processing time limits or there’s a network issue. Retry the request. Contact Revolv3 support if this persists.

Handling Validation Errors (400 Bad Request)

For incorrect data formatting or validation failures, the API returns a 400 status with an array of errors in the response body. Example for an invalid expiration date format:

{
    "message": "One or more validation failed.",
    "fluentValidatorErrors": [
        {
            "propertyName": "OneTimePaymentWithoutSubscriptionRequest.PaymentMethod",
            "errorMessage": "Expiration date needs to be in either one of the following format:  MMYY, MMYYYY, MM/YY, and MM/YYYY.",
            "attemptedValue": null,
            "customState": null,
            "severity": 0,
            "errorCode": null,
            "formattedMessagePlaceholderValues": null
        }
    ]
}

Handling Processor Failures (200 OK with Failure Status)

Even on a successful API call (200 OK), the payment processor may decline the transaction. The response includes a “Fail” status and a message. To include the full raw processor response, add "includeRawProcessorResponse": true to your payload. Example response:

{
    "customerId": null,
    "invoiceId": 396247,
    "merchantInvoiceRefId": "ABC309500654810",
    "merchantPaymentMethodRefId": null,
    "networkTransactionId": "451831812015385",
    "invoiceStatus": "Noncollectable",
    "invoiceAttemptStatus": "Fail",
    "message": "Generic Decline",
    "amount": {
        "currency": "USD",
        "value": 1.03
    },
    "paymentMethodId": 6445,
    "paymentMethodTypeId": 1,
    "rawResponse": null
}

Retrieving Additional Invoice Details

For more information on a failed or successful invoice, use a GET request to the invoice endpoint: {{Api Root}}/api/Invoices/{{Active Invoice Id}} Example response:

{
    "invoiceId": 292438,
    "parentInvoiceId": null,
    "customerId": null,
    "merchantInvoiceRefId": "ABC309500654810",
    "paymentMethod": {
        "paymentMethodId": 6446,
        "billingAddressId": 7528,
        "billingFirstName": "Joe",
        "billingLastName": "Smith",
        "merchantPaymentMethodRefId": null,
        "billingAddress": {
            "addressId": 7528,
            "addressLine1": "381 Forest Ave. Suite C",
            "addressLine2": null,
            "city": "Laguna Beach",
            "state": "CA",
            "postalCode": "92651",
            "phoneNumber": null,
            "email": null,
            "country": "US"
        },
        "paymentMethodAchDetails": null,
        "paymentMethodCreditCardDetails": {
            "binNumber": "445700",
            "paymentLast4Digit": "0005",
            "paymentExpirationDate": "0330"
        }
    },
    "invoiceStatus": "Noncollectable",
    "subtotal": 1.03,
    "tax": 0.00,
    "total": 1.03,
    "billingDate": "9/4/2024",
    "merchantLegalName": "[TEST] WP House (MD Adyen Route)",
    "merchantCustomerRefId": null,
    "customerFirstName": null,
    "customerLastName": null,
    "subscriptionId": null,
    "installmentId": null,
    "eligibilityFailReason": null,
    "merchantSubscriptionRefId": null,
    "networkTransactionId": null,
    "invoiceLineItems": [],
    "invoiceAttempts": [
        {
            "invoiceAttemptId": 134495,
            "amount": 1.03,
            "invoiceAttemptStatus": "Fail",
            "invoiceAttemptDate": "2024-09-04T18:35:39.95",
            "paymentProcessor": "WorldPay",
            "processorTransactionId": "84082941507574465",
            "responseCode": "110",
            "responseMessage": "Insufficient Funds",
            "paymentMethod": {
                "paymentMethodId": 6446,
                "billingAddressId": 7528,
                "billingAddress": {
                    "addressId": 7528,
                    "addressLine1": "381 Forest Ave. Suite C",
                    "addressLine2": null,
                    "city": "Laguna Beach",
                    "state": "CA",
                    "postalCode": "92651",
                    "phoneNumber": null,
                    "email": null,
                    "country": "US"
                },
                "billingFirstName": "Joe",
                "billingLastName": "Smith",
                "merchantPaymentMethodRefId": null,
                "paymentMethodAchDetails": null,
                "paymentMethodCreditCardDetails": {
                    "binNumber": "445700",
                    "paymentLast4Digit": "0005",
                    "paymentExpirationDate": "0330"
                }
            },
            "eligibilityCheckOrderCode": null
        }
    ]
}

Best Practices for Error Handling

Retry Logic: For 429, 502, 503, and 504 errors, implement exponential backoff retries.
Logging: Capture response codes and bodies for debugging.
User Feedback: Translate technical errors into user-friendly messages in your application.
Monitoring: Track error rates to identify integration issues early.

For further assistance, contact Revolv3 support.

Getting Started

Authentication & Security

Core Concepts & Data Models

Integration Flows

Plugins

API Reference

Webhooks & Event Handling

Error Codes & Troubleshooting

Testing & Sandbox

Certification & Go-Live Checklist

Appendix / Glossary

FAQ

Success Response Codes

Error Response Codes

Handling Validation Errors (400 Bad Request)

Handling Processor Failures (200 OK with Failure Status)

Retrieving Additional Invoice Details

Best Practices for Error Handling

​Success Response Codes

​Error Response Codes

​Handling Validation Errors (400 Bad Request)

​Handling Processor Failures (200 OK with Failure Status)

​Retrieving Additional Invoice Details

​Best Practices for Error Handling

Success Response Codes

Error Response Codes

Handling Validation Errors (400 Bad Request)

Handling Processor Failures (200 OK with Failure Status)

Retrieving Additional Invoice Details

Best Practices for Error Handling