Error Handling

HTTP status codes

When you make a request to our API, you'll receive a response in ld+json format. Along with the json data, each response contains an HTTP status code that indicates whether the request was successful or failed. If there's an error, the status code and the message in the response will explain what happened.

Successful requests

HTTP status codes 200 OK, 201 Created or 204 No Content mean that your request was successful. In the example below, we've successfully retrieved an order.

Request

console

curl -X 'GET' \
  'https://app.merchrocket.shop/api/orders/018ee630-51dd-7615-a721-d648407ceb4c' \
  -H 'accept: application/ld+json' \
  -H 'Authorization: Bearer: mrp_ad9e9d714d602e133b93ce1f5504ae2b

Response

console

HTTP/1.1 200 OK
application/ld+json; charset=utf-8 

{
  "@context": "/api/contexts/Order",
  "@id": "/api/orders/018ee630-51dd-7615-a721-d648407ceb4c",
  "@type": "Order",
  "id": "018ee630-51dd-7615-a721-d648407ceb4c",
  "externalId": "OFC4IC5F",
  "shipping": "STANDARD",
  "status": "fulfilled",
  "createdAt": "2024-04-16T09:15:10+00:00",
  "updatedAt": "2024-04-16T09:15:10+00:00",
  "recipient": {
    "name": "Flo",
    "company": "Bartoletti, Mosciski and Pagac",
    "address1": "525 O'Kon Drive",
    "address2": "",
    "city": "city",
    "stateCode": "",
    "stateName": "",
    "countryCode": "BN",
    "countryName": "Micronesia",
    "zip": "36205",
    "phone": "(575) 463-0497",
    "email": "kamren52@hotmail.com",
    "taxNumber": "ZXQIVFG4JI9"
  },
  "orderItems": [
    {
      "@id": "/api/orders/018ee630-51dd-7615-a721-d648407ceb4c/order_item/018ee630-51dd-7615-a721-d64840c80de1",
      "@type": "OrderItem",
      "id": "018ee630-51dd-7615-a721-d64840c80de1",
      "externalId": "KB-00004-RE",
      "quantity": 12,
      "name": "Mug",
      "retailPrice": "10.9",
      "variantId": "74a4dc41-de4a-46ff-bea8-8f6416bc3b3c",
      "placements": [
        {
          "@type": "Placement",
          "@id": "/api/.well-known/genid/eae77a2b1d5d9b1a822c",
          "type": null,
          "technique": null,
          "layers": [],
          "placementOptions": []
        }
      ]
    }
  ]
}

Response types

The first digit of an HTTP status code indicates its class, providing insight into how to handle errors effectively. The following classes are relevant to the Merchrocket API:

Codes in the 2xx range indicate a successful response from the Merchrocket API.
Codes in the 4xx range indicate client-side errors, meaning that the problem is in your code. You can resolve these errors by adjusting your code to prevent similar issues in the future.
Codes in the 5xx range indicate server-side errors, indicating problems with the Merchrocket API or its infrastructure. If you are experiencing these errors, it means something is wrong on our end. However, these errors should resolve themselves without requiring any action on your part.

Examples of error responses

From time to time, things may not go as smoothly as expected. For example, if you make a request with an incorrect API key, you may receive the following error:

Request

console

curl -X 'GET' \
  'https://app.merchrocket.shop/api/orders/018ee630-51dd-7615-a721-d648407ceb4c' \
  -H 'accept: application/ld+json' \
  -H 'Authorization: Bearer: invalid_key'

Response

console

HTTP/1.1 403 Forbidden
application/ld+json; charset=utf-8 

{
  "code": 403,
  "message": "Access Denied."
}

HTTP status code 403 Forbidden means that there's a problem with the authorization needed to perform the requested action.

Another common error is the HTTP status code 404 Not Found, which means the object you're attempting to read or modify doesn't exist:

Request

console

curl -X 'GET' \
  'https://app.merchrocket.shop/api/orders/does_not_exist' \
  -H 'accept: application/ld+json' \
  -H 'Authorization: Bearer: mrp_ad9e9d714d602e133b93ce1f5504ae2b

Response

console

HTTP/1.1 404 Not Found
application/ld+json; charset=utf-8

{
  "@context": "/api/contexts/Error",
  "@type": "hydra:Error",
  "hydra:title": "An error occurred",
  "hydra:description": "No route found for \"GET https://app.merchrocket.shop/api/orders/does_not_exist\" (from \"https://app.merchrocket.shop/api\")",
}

In some cases, you may receive an HTTP status code of 422 - Unprocessable Entity. When this happens, the JSON response contains additional details about which part or field of your request is likely to be causing the error. In such cases, you'll notice the "violations" field in the response. In the example below, we intentionally used an quantity that was too low:

Request

console

curl -X 'PATCH' \
  'https://app.merchrocket.shop/api/orders/018ee630-51dd-7615-a721-d648407ceb4c/order_item/018ee630-51dd-7615-a721-d64840c80de1' \
  -H 'accept: application/ld+json' \
  -H 'Authorization: Bearer mrp_4HcmEMnvJAKPiGPgUyAOBItzOLb8DpSj' \
  -H 'Content-Type: application/merge-patch+json' \
  -d '{
        "quantity": 0
      }'

Response

console

HTTP/1.1 422 Unprocessable Entity
application/ld+json; charset=utf-8

{
  "@id": "/api/validation_errors/0=778b7ae0-84d3-481a-9dec-35fdb64b1d78;1=ad32d13f-c3d4-423b-909a-857b961eb720;2=c1051bb4-d103-4f74-8988-acbcafc7fdc3;3=c1051bb4-d103-4f74-8988-acbcafc7fdc3;4=bef8e338-6ae5-4caf-b8e2-50e7b0579e69",
  "@type": "ConstraintViolationList",
  "status": 422,
  "violations": [
    {
      "propertyPath": "quantity",
      "message": "This value should be greater than 0.",
      "code": "778b7ae0-84d3-481a-9dec-35fdb64b1d78"
    },
  ],
  "detail": "quantity: This value should be greater than 0.",
  "hydra:title": "An error occurred",
  "hydra:description": "quantity: This value should be greater than 0.",
  "type": "/validation_errors/0=778b7ae0-84d3-481a-9dec-35fdb64b1d78;1=ad32d13f-c3d4-423b-909a-857b961eb720;2=c1051bb4-d103-4f74-8988-acbcafc7fdc3;3=c1051bb4-d103-4f74-8988-acbcafc7fdc3;4=bef8e338-6ae5-4caf-b8e2-50e7b0579e69",
  "title": "An error occurred"
}

All possible status codes

The Merchrocket API only returns a limited set of status codes. These are listed below:

HTTP Status Code	Description
200 - OK	The request was successful.
201 - Created	A new entity was successfully created.
204 - No Content	The requested entity was successfully cancelled or deleted.
400 - Bad Request	The server couldn't understand the request due to a possible syntax error.
401 - Unauthorized	Access to the requested resource was denied due to failed authentication. Check your API-Key.
403 - Forbidden	Access to the requested resource was denied due to insufficient permissions.
404 - Not Found	The requested resource was not found.
405 - Method Not Allowed	The HTTP method used is not supported by the resource. Refer to the Allow header for supported methods.
409 - Conflict	There's a conflict with the current state of the resource.
410 - Gone	The requested resource is no longer available.
415 - Unsupported Media Type	The request's encoding is not supported or understood. Always use JSON encoding.
422 - Unprocessable Entity	The server couldn't process the request due to another reason. The response may contain details on the issue. If your account is suspended, check your dashboard for more information.
429 - Too Many Requests	The request has hit a rate limit. Retry after a short period.
500 - Internal Server Error	An internal server error occurred while processing the request. Developers are notified automatically. Contact support if you have additional information.
502 - Bad Gateway	The service is temporarily unavailable due to calamity or maintenance. Retry the request later.
503 - Service Unavailable	The service is temporarily unavailable due to calamity or maintenance. Retry the request later.
504 - Gateway Timeout	The request is taking unusually long to process.

Order Validation & Error Codes

When an order is placed, the shipping address & print data are validated afterwards. If this is incorrect or incomplete, the errors are saved in the order or in the order items and returned via the API using the GetOrder or GetOrders endpoint. Furthermore, the order status is set to `failed and your webhook is called. The errors contain error codes so that they can be better classified.

The error codes:

1001 - If the specified print file cannot be read. (e.g. -> The uploaded file is damaged or does not exist)
2001 - If the address validation fails. (e.g. -> Shipping address: The street attribute is missing)

Error Handling ​

HTTP status codes ​

Successful requests ​

Request ​

Response ​

Response types ​

Examples of error responses ​

Request ​

Response ​

Request ​

Response ​

Request ​

Response ​

All possible status codes ​

Order Validation & Error Codes ​

Error Handling

HTTP status codes

Successful requests

Request

Response

Response types

Examples of error responses

Request

Response

Request

Response

Request

Response

All possible status codes

Order Validation & Error Codes