Errors

The platform provides RESTful APIs, and as such HTTP status codes are used to indicate the success or failure of a given request.

Generally, unless otherwise stated in the endpoint documentation, the following can be assumed: 2xx status codes indicate that the request was successful. 4xx status codes indicates an issue with the request that the client made (eg. couldn't find a product with the specified ID). 5xx codes are used to indicate a server side problem. Generally 5xx codes indicate that it is a problem with our servers or an upstream provider, and are rare. If a 5xx error code continues to be returned over an extended period of time, please contact us if necessary.

When an error is returned, the standard error format is shown in the example below:

The fields of the error response are defined as follows:

Attributes

  • Name
    type
    Type
    enum
    Restrictions
    Description

    The type of error returned. This will be one of the following values: invalid_request, rate_limit, api and authentication.

    Possible Enum Values

    invalid_request
    rate_limit
    api
    authentication
  • Name
    code
    Type
    string
    Restrictions
    Description

    A machine-readable string indicating the error that was reported. There are several possible error codes. These will be documented in the near future.

  • Name
    param
    Type
    string
    Restrictions
    Description

    Where the error has been caused by an identifiable parameter, the param field will contain a reference to said parameter. For nested parameters, such as those in objects, the value may contain a dot to indicate that the parameter is located in a nested object (eg. customer.id).

  • Name
    message
    Type
    string
    Restrictions
    Description

    A human-readable message describing the cause of the error. If no custom error message, either defined within the client or derived from the code is displayed, this message can be displayed to users. We try to focus on brevity in these error messages, and avoid technical detail where possible.

Sample Error Response
{
    "code": "insufficient_permissions",
    "message": "This account does not have permission to view the requested resource.",
    "param": null,
    "type": "authentication"
}

HTTP Status Codes

Status CodeTitleDescription
200OKThe request completed successfully.
201CreatedThe request completed successfully and the resource was created.
202AcceptedThe request was accepted, though some resources may fail to be created/updated. Usually returned by bulk endpoints.
204No ContentReturned by deletion endpoints to indicate a successful resource deletion.
400Bad RequestThe request failed. This is usually due to a missing or invalid parameter.
401UnauthorizedThe request failed due to missing or invalid authorization.
403ForbiddenThe request failed because the user does not have permission to access the requested resource.
404Not FoundThe requested resource doesn't exist.
409ConflictThe request conflicts with an existing resource. This is usually due to a parameter that is required to be unique being linked to an existing resource.
429Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500,502,
503,504		Server ErrorsSomething went wrong on our side. If these errors occur persistently you should contact support to resolve it.