Error Handling

Description

Macy's API - is "adapter" of Macys.com to remote clients. So there is we can distinguish 6 stages of using Macy's API and so 6 places of errors:

  • client can not establish connection to Macy's API
  • Macy's API can not adapt request to Macys.com
  • Macy's API can not establish connection to Macys.com
  • Macy's API can not adapt Macys.com response to client
  • Macys.com reply error response to Macy's API
  • Macy's API internal errors

First stage can not be processed by Macy's API so remains 5 types of errors returned from Macy's API. Error codes divided in 5 diapasones:

  • 100-199 Forward Compatibility Errors(1xx) - These errors are created as a result of a impossibility of translating client request to Macys API request: can not map request, incorrect arguments, etc.
  • 200-299 Connection Errors(2xx) - These errors are created as a result of a connection failing to be established to a Macys.com server. They will contain a brief description of why a connection could not be established. This class of errors contains "full stack" connections errors: TCP connection, HTTP request/responce, Hessian RPC-call. Also this class of errors contains all stages of connection establishing, using, closing, timeouting, etc. 
  • 300-399 Backward Compatibility Errors(3xx) - Macys sent correct response(in business-logic sence) to Gateway but Gateway can't convert to correct JSON.
  •  400-499 Web Server Response Codes And Messages(4xx) - call to Macys returned correct erorr message so we translate (perhaps with some transformations).
  •  500-599. Internal Errors(5xx) - Some error during processing request or general error-state of gateway or low resources for processing - no threads in pools, low free memory, etc.

In every diapasone first error code(100, 200, 300, 400, 500) has "General" sence. So in test/development/production mode we can return only 5 not specialized codes.

 

Detailed description

1. Forward Compatibility Errors(1xx)

Macy's API error code HTTP status code Description
100 400 General Forward Compatibility Errors
101 404 There is no mapping for request at all.
102 404 There is no mapping for request temporary.
103 400 Incorrect argument types or combination. Can not form args for Hessian RPC-call.
104 404 Can form args but this method temporary closed for using (by admin for example).
105 400 Incorrect HTTP-headers (no heder at all or incorrect or dublicated etc)
106 400 Unknown client ID

2. Connection Errors(2xx)

This class of errors contains "full stack" connections errors: TCP connection, HTTP request/responce, Hessian RPC-call. Also this class of errors contains all stages of connection establishing, using, closing, timeouting, etc.

Macy's API error code HTTP status code Description
200 502 General connection error ("Connection error")
TCP:

201 504 Can not establish TCP connection ("Connection error")
202 504 Timeout establishing TCP connection ("Connection error")
203 502 IOException exception during using TCP connection ("Connection error")
204 504 Timeout reading data from TCP connection ("Timeout error")
HTTP:

220 502 Wrong HTTP response ("Connection error")
Hessian RPC:

240 500 Internal Hessian transport exception (like IOException) ("Connection error")
241 502 Hessian serialization exception (like ClassNotFoundException) ("Connection error")
242 400 Secure connection required

 

3. Backward Compatibility Errors(3xx)

Macy's API error code HTTP status code Description
300 500 General Backward Compatibility Error ("Cant form result")
301 500 Type mismatch ("Remote-local type mismatch")

 

4. Web Server Response Codes And Messages(4xx)

Macy's API error code HTTP status code Description
400 502 General Macys error ("Remote error").
401 502 Unknown Macys error ("Unknown remote error").
402 404 No data ("No data").
403 400 Upgrade required for client id.
404 403 Access denied for client id.
405 401 Authentication required.
406 500 Authentication failed.
407 400 Invalid data type.

 

5. Internal Errors(5xx)

Macy's API error code HTTP status code Description
500 500 General internal error ("Internal error").
501 500 Unknown exception ("Unknown internal error").
502 503 Server too busy ("Server too busy").
503 503 Server temporary unavailable ("Server temporary unavailable").
504
Config file not found
505
Unable to read config file(Permission denied/Corrupt file)
506 504 Gateway Timeout

 

6. REST Framework

HTTP StatusError CodeDescription
500 02001 Generic server error
500 02002 Server error during exception processing
406 02003 Unsupported Accept header
404 02004 Unsupported resource URL
405 02005 Unsupported HTTP method
400 02006 Mandatory header 'X-Macys-RequestId' is not specified 
400 
02007 
Mandatory header 'X-Macys-ClientId' is not specified or has invalid value 
400 02008 Mandatory header is not specified 

7. converter.util

HTTP StatusError CodeDescription
400 03001 Error in _fields parameter while calling REST resources
400 03002 Error in _fields parameter while calling REST resources
400 03003 Error in _fields parameter while calling REST resources
400 03004 Error in _fields parameter while calling REST resources

8. store.service

HTTP StatusError CodeDescription
400 04001 Invalid number of stores. Number of Stores should be positive
400 04002 Invalid geo coordinates. Latitude should be in range from -90 to 90.
400 04003 Invalid geo coordinates. Longitude should be in range from -180 to 180.
400 04004 Invalid ZIP code.
400 04005 Invalid Address. The length of address cannot be larger then given value
400 04006 Invalid City. The length of city cannot be larger then given value
400 04007 Invalid state abbreviations. The length of state abbreviations has to be equaled given value
400 04008 Invalid state abbreviations. The state abbreviations has to consist of characters
400 04009 One of required parameters should be specified
400 04010 Width should be from 1 to given value
400 04011 Height should be from 1 to given value
400 04012 Width and Height should be specified together
400 04013 Zoom should be in defined range
400 04014 Bad request. Unsupported request with both params: id and storeNumber
400 04015 Bad request. Unsupported request with both params: productId and upcNumber
400 04016 Bad request. Invalid state code. State code must be not
410 04017 Hessian store service is no longer supported. Use REST instead
410 04018 store/v1/stores resource is no longer supported. Use store/v2/stores instead

9. store.provider

HTTP StatusError CodeDescription
400 05001 Unable to find specified location for ZIP code (MapQuest only)
400 05002 Unable to find specified location for city (MapQuest only)
400 05003 Unable to find specified location for address
400 05004 Size of parameter 'upcNumbers' is exceeded.
500 05005 Google quota exceeded for service

10. catalog.service(FCC)

HTTP StatusError CodeDescription
500 17001 Generic server business error
404 17002 Country specified in the parameters is not present in the database
500 17003 Generic server technical error

 

Sample Errored Request and Response

Sample Request 1

URL:

 http://api.macys.com/v1/catalog/reviews?productId=7758

HTTP Header:

x-macys-webservice-client-id: 123456789 (The API key is wrong in this case.  It should be xmj9js4jkdpe1983fmwu98gh not 123456789.  You will also get this response if your keys are not activated. Please reach out to apisupport@macys.com if you are having trouble getting your key approved)

Accept: application/json

 

Http Status: 403 Forbidden

Response:

{Developer Inactive}


Sample Request 2

URL:

 http://api.macys.com/v1/catalog/reviews?productId=7758 (The URL in this case is trying to hit a v1 service that does not exist.  It should be v3 not v1)

HTTP Header:

x-macys-webservice-client-id: xmj9js4jkdpe1983fmwu98gh

Accept: application/json

 

Http Status: 404 Not Found

Response:

{errorCode: 101
message:"There is no mapping for request"
-errorDetail: [1]
0: "<a href="http://services2.macys.com/resources/v1/catalog/reviews?productId=7758" _mce_href="http://services2.macys.com/resources/v1/catalog/reviews?productId=7758" title="Click to insert into URL field">http://services2.macys.com/resources/v1/catalog/reviews?productId=7758</a>"
success:false}

 

back to top

Docs Navigation