HTTP Status Codes

This API refers to the conventional HTTP response codes to indicate success or failure:

  • 2xx status code is generally considered successful.
  • 4xx status code means that there was an error with the inputs.
  • 5xx status code means that we’ve experienced an unexpected error and means we screwed up!

Your code must correctly interpret HTTP status codes returned by Joom API as they are part of the response. In case of an error response, more detailed information can be found in the JSON response body.

HTTP status codes normally used by Joom API are:

Code Meaning Troubleshooting
200 Success All went well. Get your response.
400 Bad Request You need to fix your request to proceed. See the error details in the JSON response. There may be a mistake in the request parameters (e.g. string in JSON integer field) or you’re trying to perform an operation that is incosistent with the current state of the resource (e.g. trying to fulfill a cancelled order).
401 Unauthorized Please provide a valid access token with your request.
403 Forbidden You’re trying to access a resource that you’re not allowed to access. E.g. you’re authenticated as one of the merchant’s store, but you’re trying to access a product or an order from a different store.
404 Not Found You’re trying to access a resource that does not exist. E.g. you’ve accidentally used Joom Product ID in the sku parameter, we cannot find your product with such SKU.
429 Too Many Requests You’ve exceeded our request rate quota. Implement request limiting on your side according to our requirements.
500 Internal Server Error Something went wrong on our side. Please try repeating the request a bit later. Probably, we’re already aware of the problem and will do our best to fix it, but it may take time. If this error still happens after several retries for a significant amount of time, contact Joom Merchant Support.

Request ID

When you report a problem regarding Joom API to Joom Merchant Support, you may be asked to provide the request id for the request in question.

Each response contains the following header:

request-id: {request id}

Request ID is a short string containing latin letters and numbers, usually starting with symbol j. It is a unique identifier for the request that can help Joom developers to debug a problem with a particular request.

Please, save this request id in your request logs. (We hope you use logging when interacting with Joom API.)

Please note:

If you don’t provide a request id when reporting a problem to Joom Merchant Support, Joom developers may be unable to investigate your case.

Response Schema

All responses from the Joom API come in JSON, except those that contain file data (e.g. PDF).

Every JSON response will consist of some of the following top-level fields:

Name Type When returned Description
data object On success, if applicable The response data that was requested.
paging object On success, if applicable If the number of results exceeds the limit for the request, this parameter will aid the client in paging to collect all the results. See details here.
errors array of objects On error A list of errors that occurred during the request processing. See details here.