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.
201 (Created)	The resource was created successfully (e.g., a customer, address, payment method, subscription, or billing plan). The response body contains the new resource.
204 (No Content)	Request successful, but no data to return (e.g., a successful deletion or update without content, or a list request with no results).

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.
401 (Unauthorized)	The request couldn’t be authenticated or isn’t allowed. Common causes: missing or invalid `x-revolv3-token`, or a sandbox token used in production (or the reverse). The body can also say `Attempted to perform an unauthorized operation.` when the credential doesn’t have permission for the operation. See Authentication.
404 (Not Found)	Requested resource not found (e.g., customer, subscription, or invoice).
409 (Conflict)	The request conflicts with another request that is still in progress. For example, `PaymentMethodAuthorizationId is being processed in another request.` Returned by `POST /api/Invoices/payment` and `POST /api/Subscriptions`. Wait for the other request to finish, then retry if needed. Don’t send the same request again at the same time.
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.

Request IDs for Troubleshooting

Every API response includes a Request-Id header. You can send an optional Client-Request-Id, and error bodies include serverRequestId. See Request IDs for the header format, examples, and what to send support.

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.",
    "serverRequestId": "4bf92f3577b34da6a3ce929d0e0e4736",
    "clientRequestId": "order-104821",
    "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, bodies, and the Request-Id response header. See Request IDs.
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

Request IDs for Troubleshooting

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

​Request IDs for Troubleshooting

​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

Request IDs for Troubleshooting

Handling Validation Errors (400 Bad Request)

Handling Processor Failures (200 OK with Failure Status)

Retrieving Additional Invoice Details

Best Practices for Error Handling