Error Handling

1. Overview
2. The Basics
3. The Details
   1. 400, 401 & 404
   2. 412 Precondition Failed
   3. 422 Unprocessable Entity
   4. 500 Internal Server Error
   5. 502 Naughty Gateway
   6. 503 Planned Downtime
4. The Gory Details
5. Duplicate Checks
6. Building Tolerance into Your Application
7. There's Errors and Then There's Errors
8. Error Simulation
   1. Real-time Error Simulation
   2. Delayed Error Simulation
9. More Information About Errors

1. Overview

One of the great values that Cheddar provides is its simplified error reporting. We've done all we can to eliminate the error handling hassles that come with online billing and subscription management. Payment gateways can have hundreds of unique error codes. In the real world, you'll only see a tiny fraction of them and most of those will be the ones you want (e.g. invalid credit card expiration date). We've narrowed it down for you. Here it is.

2. The Basics

First of all, the basics. Errors reported by the API look something like this:

XML

<error id="12345" code="422" auxCode="5003">
    Credit card type is not accepted
</error>

JSON

{
  "error": {
    "id": 12345,
    "code": 422,
    "auxCode": "5003",
    "message": "Credit card type is not accepted"
  }
}

If the customer does not exist yet, only the error node will be returned. If the customer already exists, the error node will be embedded in the customer response, like so:

<customers>
    <errors>
        <error id="1235" code="422" auxCode="6000">The transaction was declined</error>
    </errors>
    <customer id="d665b62a-0fc9-102d-844d-94789ca76f11" code="YOUR_CODE">
        <firstName>Example</firstName>
        <lastName>Customer</lastName>
        .
        .
        .

Cheddar exposes errors, and in some cases additional information about errors, to you in the admin GUI under Reports->Errors

3. The Details

Cheddar breaks up errors into categories for you based on HTTP status code. The HTTP status code is produced in the response header and the code attribute of the error node corresponds to that same HTTP status code. Here's a list of the status codes that Cheddar produces:

• 400 Bad Request: The request was invalid.
• 401 Not Authorized: Authentication credentials were missing or incorrect or you are not authorized to use the requested resource.
• 404 Not Found: The URI requested is invalid or the resource requested, such as a user, does not exist.
• 412 Precondition Failed: The request contains POST data that is in an invalid format or required parameters are missing.
• 422 Unprocessable Entity: A error occurred during processing. Please fix the error and try again.
• 500 Internal Server Error: Something is broken. Please post in the support forum so the Cheddar team can investigate.
• 502 Bad Gateway: Communication with the payment gateway failed. Try again later.
• 503 Service Unavailable: Cheddar is temporarily offline for maintenance. Try again later.

An accompanying message will explain the error in greater detail.

400, 401 & 404

400, 401 and 404 usually result from something you can fix pretty quickly in your app. Once you do, an instance of that error shouldn't happen again. The accompanying error message will tell you exactly what you need to know. There might be more information in the error report.

The 412

The 412 Precondition Failed error is special. Your customer may have entered some data that has gotten past your own input filtering and validation. If this happens, an error will be produced and the auxCode attribute of the error node will give you the info you need. Here's an example of a 412 error:

<error id="12345" code="412" auxCode="firstName:isEmpty">
    A value is required
</error>

This error would be produced if you tried to create a new customer without a firstName value. The auxCode attribute contains the field name and the error type separated by a colon :. Refer to the API Documentation for information about field requirements and formats. More information about the fields that failed validation can be found in the error report.

This error will also be produced if your customer attempts to add a tracked item or change to a pricing plan in a way that doesn't align with item or plan limits you've set in Cheddar. For example, if you've set a hard limit for a tracked item of 100 and customer attempts to use more than that number, when your system attempts to set the quantity to 101 on the customer's upcoming bill, Cheddar will return a 412 error with the aux code attribute of quantity:notLessThanOrEqual. You can utilize these errors to control access to certain features of your website and to prompt the customer to upgrade their plan. For more information, see Using Item Quantity Restrictions for Upselling.

The 422

The 422 Unprocessable Entity is similar to the 412 error in that it is due to an error in input but it is related to payment data only. This error will be produced if all data passes Cheddar's validation and is sent to the payment gateway for processing which in turn rejects the data. When this happens, the auxCode will tell you everything you need to know. The content of the error message, while somewhat simple, is fit for human consumption but you might wish to change it. There might be more information in the error report.

500 (Oops)

We hope to never see a 500 error but we're human so it's possible. If a 500 is produced, it means that Cheddar goofed. Whenever a 500 happens, red flags wave and buzzers and bells ring around here. Rest assured, we're on top of it. See Building Tolerance into Your Application.

502 Naughty Gateway

When a 502 happens, it means that Cheddar was either unable to communicate with your gateway or the gateway did something extra screwy that Cheddar's never seen before. If we can prevent it from happening again, we will but sometimes the internet breaks and there's nothing that Cheddar can do about it. Sad but true. There might be more information in the error report.

503 Planned Downtime

HTTP status 503 will be returned when the system is in a maintenance state. This situation is temporary and should last only a short time. See Building Tolerance into Your Application.

4. The Gory Details

Here's where Cheddar translates what it receives from your gateway into something useful and stuffs it into the auxCode attribute. As always, you may find more information in your error log. While interacting with a gateway, Cheddar can produce the following codes:

5. Duplicate Checks

The following API endpoints include a check for duplicate POST requests:

• customers/new
• customers/edit
• customers/edit-subscription
• customers/add-charge
• invoices/new

A duplicate identical POST request sent to any of these endpoints within a window of 10 seconds is considered to be invalid and will receive a 400 status response with auxCode=duplicate. A request is considered a duplicate if it contains the same POST parameters with the same values as a previous request, no more no less.

6. Building Fault Tolerance into Your Application

The interwebs aren't perfect. It's important to tolerate its quirks and nuances so that your application doesn't freak out in the event of a failure. Here's a guide to the general types of failures that can occur and how you can develop your integration to tolerate them:

1. When Cheddar has been taken offline intentionally the API will return a simple error response with HTTP status=503. When your app experiences a 503 response, you should consider this temporary and handle the event appropriately. We don't often have intentional downtime where a 503 is necessary but sometimes there's no way around it. In the case of planned downtime, you can expect to be notified in advance. You can test this with Error Simulation.
   
2. It's possible that Cheddar will return a 500 HTTP status in the event of an unknown failure within Cheddar's processing of any API request. Again, this scenario should be considered temporary. You can test this with Error Simulation.
   
3. Connection failure or timeout. Your app's HTTP library should provide a mechanism for detecting a connection failure so that your app logic can behave accordingly.
   
4. Read failure or timeout. This can happen when connection to Cheddar is successful and the request is sent but your app does not receive a response from Cheddar. Your app's HTTP library should provide a mechanism for detecting a read failure so that your app logic can behave accordingly.

To keep things simple, you might consider a broad stroke solution for all of the above scenarios. Perhaps deferring to an expired cached customer status or limiting access to your app during this period would be appropriate. In short, it's up to you to decide how your app should behave under these conditions.

7. There's Errors and Then There's Errors

Errors can occur in one of two general ways. In one, the entire action requested failed. In the other, some portion of the action was successful and then something failed. The first example is very simple. The bulk of errors are of this type:

<error id="1234" code="422" auxCode="6000">
    The transaction was declined
</error>

The second example is a little more complicated but only because it combines a standard xml response with embedded errors. For example, a customer is created and subscribed to a pricing plan with a setup fee. When Cheddar tries to run the setup fee invoice transaction, the transaction is declined.

<customers>
    <errors>
        <error id="1235" code="422" auxCode="6000">The transaction was declined</error>
    </errors>
    <customer id="d665b62a-0fc9-102d-844d-94789ca76f11" code="YOUR_CODE">
        <firstName>Example</firstName>
        <lastName>Customer</lastName>
        .
        .
        .
        <subscriptions>
            <subscription id="2b13dc42-0fca-102d-844d-94789ca76f11">
                <invoices>
                    <invoice id="2bb6bb24-0fca-102d-844d-94789ca76f39">
                        <type>setup</type>
                        .
                        .
                        .
                        <transactions>
                            <transaction id="2d237e5c-0fca-102d-844d-94789ca76f11">
                                .
                                .
                                .
                                <response>declined</response>
                                <responseReason>The transaction was declined</responseReason>
                                .
                                .
                                .
                            </transaction>
                        </transactions>
                    </invoice>
                    .
                    .
                    .
                </invoices>
            </subscription>
        </subscription>
    </customer>
</customers>

8. Error Simulation

You can simulate all of the payment gateway related errors that Cheddar can return by using a customer's credit card billing address postal code (or API parameter ccZip) in a specific way. The error codes that can be simulated are listed in the AUXCODE column of the table here.

Error simulation is only enabled when your payment processor is in simulation mode. As soon as you setup a live payment processor, error simulation is disabled.

There are two ways of simulating these errors: real-time errors, and delayed errors.

8.1 Real-time Error Simulation

Real-time errors are those that occur when a customer's credit card is initially validated. This occurs when a new customer is subscribed to a paid plan or when a customer's credit card information is changed. If the POST data passes Cheddar's validation and Cheddar will need to interact with the gateway, the error simulation occurs. In order to trigger the error simulation, the customer's billing postal code must be sent in the following format: 0XXXX, where XXXX is one of the AUXCODE's listed here.

8.2 Delayed Error Simulation

Delayed errors occur after a customer's credit card information is successfully validated and a subsequently generated transaction fails. This could happen, for example, if the setup charge for the subscribed plan is $100 and the customer's credit card only has a balance of $50. In this case, the credit card will validate successfully because it has a positive available balance but the transaction for the setup charge will fail because the balance on the card is not sufficient. Simulated delayed errors are triggered in a way similar to real-time simulated errors. The only difference is that the customer's billing postal code must be sent in the following format: 9XXXX (note the 9 instead of 0), where XXXX is one of the AUXCODE's listed here.

A good use of delayed error simulation is to test your app's behavior during the various error conditions when Cheddar automatically runs a recurring transaction.

9. More Information About Errors

Detailed information not conveyed via error messages in the GUI and API can be found in the error report. The error report can be found under Reports->Errors or here. Basic information is given via the API error node:

<error id="12345" code="401" auxCode="2001">
    The configuration at the gateway is incompatible
</error>

The error report will show you the details specific to your gateway. Maybe something like this:

The configuration at the gateway is incompatible
   * 33:Phone is required.
   * message:Phone is required.

View Plans and Pricing   or   Get Started with Cheddar now →