> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revolv3.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Revolv3 API Response Codes and Errors

> Comprehensive reference for HTTP status codes and error responses in the Revolv3 API. 

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:

```json theme={null}
{
    "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:

```json theme={null}
{
    "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:

```json theme={null}
{
    "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.