Error Handling

When the REST API encounters an error, all processing is stopped and an error response is returned to the client. No accounts are created when an error is encountered.

There are two levels of errors that are returned in the API:

  • Order Errors
  • Account Errors

Order Errors

Order errors are defined as errors that occur in the root order container and apply to the order in its entirety rather than a specific recipient. Examples of order level errors are Duplicate Client ID or Invalid Program ID.

Account Errors

Account errors are defined as errors that are related to a specific account inside the order. Examples of account level errors are Missing First Name or Invalid Email Address.

Definitions

FieldTypeDescription
CodeintegerReference code that relates to an error message. See Appendix B for definitions.
FieldstringRequest field that contains the error.
MessagestringDetailed error message.

Examples

In the examples provided below, there are multiple errors returned for the requested reward:

  • Duplicate Client ID
  • Invalid Amount
  • Invalid SKU
  • Missing Last Name

Request XML

<order>  <programid>26490</programid>
 <clientid>56258125</clientid>
 <accounts>
  <account>
   <firstname>John</firstname>
   <lastname></lastname>
   <email>[email protected]</email>
   <sku>UVC-V-A18</sku>
   <amount>0.99</amount>
  </account>
 </accounts>
</order>

Response XML

<order>
 <programid>26490</programid>
 <clientid>56258125</clientid>
 <number>24515465</number>
 <date>2016-10-11T11:58:20.41</date>
 <status>Canceled</status>
 <errors>
  <error>
   <code>90</code>
   <field>clientid</field>
   <message>Duplicate Client Id</message>
  </error>
 </errors>
 <accounts>
  <account>
   <firstname>John</firstname>
   <lastname>Doe</lastname>
   <email>[email protected]</email>
   <sku>UVC-V-A18</sku>
   <amount>0.99</amount>
   <errors>
    <error>
     <code>80</code>
     <field>lastname</field>
     <message>Field is required</message>
    </error>
    <error>
     <code>50</code>
     <field>sku</field>
     <message>Sku not found</message>
    </error>
    <error>
     <code>60</code>
     <field>amount</field>
     <message>
      Amount requested outside
      allowable denomination
     </message>
    </error>
   </errors>
  </account>
 </accounts>
</order>

Request JSON

{
 "order":{
  "programid":"26490",
  "clientid":"56258125",
   "accounts":[
    {
     "firstname":"John",
     "email":"[email protected]",
     "sku":"UVC-V-A18",
     "amount":"0.99",
     "udf1":"101",
     "udf2":"1004"
    }
   ]
  }
 }
}

Response JSON

{
 "order":{
  "programid":"26490",
  "clientid":"56258125",
  "number":"24515465",
  "date":"2016-10-11T11:58:20.41"
  "status":"Canceled"
   "errors":{
    "code":"90",
    "field":"clientid",
    "message":"Duplicate Client Id"
   }
  },
   "accounts":[
    {
     "firstname":"John",
     "lastname":"Doe",
     "email":"[email protected]",
     "sku":"UVC-V-A18",
     "amount":"0.99",
     "udf1":"101",
     "udf2":"1004",
      "errors":[
       {
        "code":"80",
        "field":"lastname",
        "message":"Field is required"
       },
       {
        "code":"50",
        "field":"sku",
        "message":"Sku not found"
       },
       {
        "code":"60",
        "field":"amount",
        "message":"Amount requested
         outside allowable denomination"
       }
      ]
     }
    }
   ]
  }
 }
}