Shopify Transaction Error Handling
- Prateek Kaushik (Unlicensed)
POST API
MARKING ORDER AS PAID ON SHOPIFY
https://{{store-name}}.myshopify.com/admin/api/2021-04/orders/{order_id}/transactions.jsonPOSSIBLE ERROR RESPONSES
In the following table, the Maximum number of cases are covered with Request, Response with Status Code and the Possible Reason behind these errors.
Case # | REQUEST | RESPONSE STATUS CODE | POSSIBLE REASON | Retryable |
|---|---|---|---|---|
#1 | “transaction“ key name is malformed | 400 BAD REQUEST |
| No |
#2 | No Access Token provided | 401 UNAUTHORIZED |
|
|
#3 | Invalid Access Token provided | 401 UNAUTHORIZED |
|
|
#4 | Not having required Scopes in the Access Token to make HTTP REQUEST on an API | 403 FORBIDDEN |
|
|
#5 | “order_id“ value is passed | 404 NOT FOUND |
|
|
#6 | “store name“ passed for URL preparation | 404 NOT FOUND |
|
|
#7 | When the parameter value “amount” is not passed as a value | 422 UNPROCESSABLE ENTITY |
|
|
#8 | When the parameter value “kind” is not passed as a value | 422 UNPROCESSABLE ENTITY |
|
|
#9 | When the correct “amount“ and “kind“ values are passed | 422 UNPROCESSABLE ENTITY |
|
|
#10 | Marking Orders as Paid more than the Shopify Store throtlling limit | 429 TOO MANY REQUESTS |
|
|
#11 | HTTP Request is correct but 5XX is returned by Shopify | 5XX Errors |
|
|
1. 400 BAD REQUESTS:
Definition: Generally it occurs due to Malformed Request Syntax. Without modifying or rectifying the syntax/request, the server will continue giving 400 Bad Request.
Case #1: When the wrong parameter key “transaction“ is passed
REQUEST
{
"transacti": {
"currency": "INR",
"amount": "10",
"kind": "capture"
}
}RESPONSE
STATUS CODE: 400 Bad Request
{
"errors": {
"transaction": "Required parameter missing or invalid"
}
}2. 401 UNAUTHORIZED:
Definition: We have two Scenarios here given as following:
Case a. Credentials Not Provided(Access token not Provided): If the credentials are not provided while making the HTTP Request, then the server will refuse to accept and will throw 401 Unauthorized error. For e.g: Authentication Token is not provided then the server will not accept the HTTP request.
RESPONSE
STATUS CODE: 401 Unauthorized
{
"errors": "[API] Invalid API key or access token (unrecognized login or wrong password)"
}
Case b. Credentials Are Provided(Invalid Access Token or Malformed Access Token): If the credentials are provided but still server is throwing 401 Unauthorized error then its most likely that the Authentication token is expired and we need to generate a new Access Token using the Refresh Token which is saved while generating Authentication/Access Token for the very first time.
RESPONSE
STATUS CODE: 401 Unauthorized
{
"errors": "[API] Invalid API key or access token (unrecognized login or wrong password)"
}
3. 402 PAYMENT REQUIRED:
Definition: The requested shop is currently frozen. The shop owner needs to log in to the shop's admin and pay the outstanding balance to unfreeze the shop.
RESPONSE
STATUS CODE: 402 Payment Required
**NOTE: Need to figure out how to get this error4. 403 FORBIDDEN:
Definition: If the scopes related to Transaction API is not present in the Access token, then this error can occur.
RESPONSE
STATUS CODE: 403 Forbidden
{
"errors": "[API] This action requires merchant approval for write_orders scope."
}5. 404 NOT FOUND:
Definition: If the following parameters required to make a HTTP request for Transaction API are not correct then a 404 NOT FOUND Error can take place:
i. store name
ii. orderID
RESPONSE
STATUS CODE: 404 Not Found
https://{{store-name}}.myshopify.com/admin/api/2021-04/orders/{{orderID}}/transactions.json6. 422 UNPROCESSABLE ENTITY:
Case #1: When the parameter value “amount” is not passed as a value
REQUEST
{
"transaction": {
"currency": "INR",
"amount": "",
"kind": "capture"
}
}RESPONSE
STATUS CODE: 422 Unprocessable Entity
{
"errors": {
"base": [
"Presentment amount cannot be more than the remaining 405.22 for this payment."
]
}
}Case #2: When the parameter “kind” value is not passed
REQUEST
{
"transaction": {
"currency": "INR",
"amount": "10",
"kind": ""
}
}RESPONSE
STATUS CODE: 422 Unprocessable Entity
{
"errors": {
"kind": [
"cannot be blank"
]
}
}Case #3: When the parameter “amount” value is passed but less than zero
REQUEST
{
"transaction": {
"currency": "INR",
"amount": "-10",
"kind": "capture"
}
}RESPONSE
STATUS CODE: 422 Unprocessable Entity
{
"errors": {
"base": [
"Presentment amount must be greater than zero."
]
}
}
7. 429 TOO MANY REQUESTS:
Definition: The request was not accepted because the application has exceeded the rate limit. See the API Call Limit documentation for a breakdown of Shopify's rate-limiting mechanism.
RESPONSE
STATUS CODE: 429 TOO MANY REQUESTS
{
"errors": "Exceeded 2 calls per second for api client. Reduce request rates to resume uninterrupted service."
}8. 5XX RESPONSE CODE:
Definition: Following Possible 5XX errors can take place:
i. 500 Internal Server Error An internal error occurred in Shopify. Please post to the API & Technology forum so that Shopify staff can investigate.
ii. 501 Not Implemented The requested endpoint is not available on that particular shop, e.g. requesting access to a Plus-specific API on a non-Plus shop. This response may also indicate that this endpoint is reserved for future use.
iii. 503 Service Unavailable The server is currently unavailable. Check the status page for reported service outages.
iv. 504 Gateway Timeout The request could not complete in time. Shopify waits up to 10 seconds for a response. Try breaking it down in multiple smaller requests.
Draft: Proposed Solutions
1. 400 BAD REQUESTS: Configure Google Cloud Alert System
Resolution:
i. Check the correct syntax and set of values in the manual or online documentation which can be helpful before making a HTTP request, once the required format is achieved, the server will respond with the appropriate response.
ii. For failure case, configure google cloud alert system
Retry: Retrying again with the same request body will not solve the problem here, we need to achieve the correct format/syntax, then only we should make the HTTP request.
2. 401 UNAUTHORIZED: Configure Google Cloud Alert System
call GET /connection/{{connectionID}}/generateToken |
call the connectionChannelData Method |
Retry with new token |
Log the response(success or failure) and retry only once |
For failure case, configure google cloud alert system |
Retry: Once the new Access Token is generated then we have to make the HTTP Request and the following Scenarios can take place:
i. Server throws 401 Unauthorized again, in this case, we just have to log the response and need to configure Google Alert System.
ii. Server gives 2XX Status Code, then Proceed as decided.
3. 402 PAYMENT REQUIRED: Configure Google Cloud Alert System
**NOTE: Need to figure out how to get this errorResolution: Nothing to be done here.
Retry: No Retry in this case.
4. 403 FORBIDDEN: Configure Google Cloud Alert System
**NOTE: Need to generate a token which does not have the required scope of the Shopify APIResolution: To rectify 403, Possible scenarios and steps can take place:
i. Check the appropriate scopes which are required to perform the HTTP Request. It is necessary to have the valid scopes in the token with which the HTTP Requests are taking place. Without Appropriate and required scopes, HTTP Requests will not succeed and will continue giving 403 Forbidden Error.
ii. Scopes are valid in the token while making the HTTP Request but the Server is still throwing 403 Forbidden Error due to invalid HTTP Method defined. For e.g, if the API does not require any Request Body or it is just a GET Request API, then it is necessary to check the HTTP Method set for this API in the code. If the HTTP Method is set other than GET, let's say PUT, POST, DELETE etc then the Server will continue giving 403 Status Code
Retry: No Retry in this case because retrying the same HTTP request without auditing the code or Access Token will not help in succeeding.
5. 404 NOT FOUND: Configure Google Cloud Alert System
Resolution: We need to find the correct parameters passed while making the HTTP Request, until and unless we have the correct URL and the correct Parameters to pass in the Request, HTTP 404 NOT FOUND Error will continue coming and will not succeed on Retry.
Retry: No Retry in this case until we have the correct URL and Correct Parameters to pass.
6. 422 UNPROCESSABLE ENTITY: Configure Google Cloud Alert System
Resolution: We can check the following points to resolve 422 as given below:
Incorrectly formatted input
Checking out products that are out of stock
fulfilling an order which is already fulfilled
Marking the order as paid which is already marked as paid
Creating a customer without an email or name
Creating a product without a title
There can be more possible reasons due to which 422 Status Code is returned.
Retry: No Retry in this case. We need to identify the root cause in before making the HTTP Request, otherwise, the Server will continue throwing 422 Unprocessable Entity Status Code.
7. 429 TOO MANY REQUESTS: Configure Google Cloud Alert System
Resolution:
Retry:
8. 5XX Errors: Configure Google Cloud Alert System