Responses

The Commerce API returns standard HTTP status codes. Most endpoints return Json-Encoded responses. Some endpoints also return contextual HATEOAS links.

Codes in the 2xx range indicate success. Codes in the 4xx range indicate that the information provided for the request is invalid. Codes in the 5xx range indicate an error in the Commerce servers.

Errors

The Commerce API uses the RFC 7807 Problem Details specification to indicate the failure of an API request.

HTTP Status Codes

Successful Requests (2xx)

Status Code	Description
`200 OK`	The request succeeded.
`201 Created`	The request succeeded, and a new resource was created as a result.
`202 Accepted`	The request has been received but not yet acted upon.
`204 No Content`	The request succeeded, but without a response body.

Failed Requests (4xx)

Status Code	Description
`400 Bad Request`	The request was unacceptable, usually due to missing a required parameter. See Validation Errors.
`401 Unauthorized`	The access token could not be authenticated.
`401 Unauthorized`	The access token did not have permissions to the requested resource.
`403 Forbidden`	The access token did not have permissions to perform the request.
`404 Not Found`	The requested resource was not found.
`405 Method Not Allowed`	The request method is known by the server but is not supported by the target resource. Example: `PATCH`.
`406 Not Acceptable`	The server cannot use the client-request media type to return the response payload. (The request is most likely missing an `Accept: application/json` header.)
`409 Conflict`	The request conflicts with the current state of the server. (Most likely due to a resource that already exists.)
`415 Unsupported Media Type`	The media format of the requested data is not supported by the server. (The request is most likely missing a `Content-Type: application/json` header.)
`429 Too Many Requests`	Too many requests in a given amount of time.

Server Error Responses (5xx)

Status Code	Description
`500 Internal Server Error`	An unhandled system or application error occurred.
`501 Not Implemented`	The request method is not supported by the server and cannot be handled. (Most likely due to a feature that has not been implemented yet.)
`503 Service Unavailable`	The server is not ready to handle the request. (The server might be overloaded or down for maintenance.)
`504 Gateway Timeout`	This error response is given when the server is acting as a gateway and cannot get a response in time. (Most likely due to an unavailable service dependency.)

Examples

For all errors except 401 Unauthorized the Commerce API returns an HTTP status code and a Problem Details response body.

Copy

Copied

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "Not Found",
  "status": 404,
  "detail": "Connection with id 123 not found.",
  "traceId": "00-27822f747ddd2d1a4ea898bcd1e5cf27-8098c98f274b7de7-00"
}

Validation Errors

For validation errors, the Commerce API returns a Problem Details response and the HTTP 400 Bad Request response. The response body will contain an errors field that contains a list of all the validation errors that occurred. Each item in the errors list indicates the name of the parameter that failed validation, and lists the reasons why the validation failed for that parameter.

Example response

Copy

Copied

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-f136bd773da894bb098bf7f48075fff1-b69d87a0b20cd716-00",
  "errors": {
    "Name": [
      "'Name' must be between 1 and 40 characters. You entered 0 characters.",
      "Name can only contain letters, numbers and underscores."
    ]
  }
}