HTTP API Errors

The following is a description of common HTTP error codes used in the commercetools™ platform APIs and their common meaning. For details about the structure and application-specific error-codes of a specific commercetools™ platform web service, consult the documentation dedicated to that service.

Common HTTP Error Codes

400 Bad Request

Affected HTTP methods: GET, POST, PUT, DELETE

A 400 is the most commonly expected error response and indicates that a request failed due to providing bad input. Bad input can be a malformed request body, missing required parameters, wrongly typed or malformed parameters or a parameter that references another resource that does not exist. Clients need to resolve the problems mentioned in the response before re-sending the request.

401 Unauthorized

Affected HTTP methods: GET, POST, PUT, DELETE

A 401 indicates that the request is not properly authenticated.

403 Forbidden

Affected HTTP methods: GET, POST, PUT, DELETE

A 403 indicates that the authenticated client is not allowed to perform the request.

404 Not Found

Affected HTTP methods: GET, POST, PUT, DELETE

A 404 indicates that the addressed resource was not found / does not exist.

409 Conflict

Affected HTTP methods: POST, PUT, DELETE

A 409 indicates that the resource targeted by the request (with the intention to modify or delete the resource), was modified since the last time the client has requested it. As a reaction, the client will usually want to request the newest version of the resource to see what has changed and may then decide to apply the same or other changes to the new version, or discard his changes entirely.

Conflicts indicate a concurrent modification and usually occur on versioned resources, for which the client has to include the version of the resource whenever he intends to apply modifications to it.

Whenever possible the HTTP response body contains the currentVersionfield (optional) like this:

{
  "statusCode": 409,
  "message": "Version mismatch. Concurrent modification.",
  "errors": [
    {
      "code": "ConcurrentModification",
      "message": "Version mismatch. Concurrent modification.",
      "currentVersion": 2
    }
  ]
}

500 Internal Server Error

Affected HTTP methods: GET, POST, PUT, DELETE

A 500 indicates that a request failed due to a server-side problem that needs to be resolved before subsequent requests can succeed. It either indicates a temporary unavailability or permanent server-side problem that needs to be reported and resolved.

Error responses

The general structure of error responses from the Projects Web Service is as follows:

{
  "statusCode": 400,
  "message": "First error message",
  "errors": [
   { "code":"SomeErrorCode", "message": "First error message" },
   { "code":"SomeErrorCode", "message": "Second error message" }
  ]
}

Note the following:

The following sections describe the possible errors in the following way:

The service always tries to report as many errors in a single response as possible, which is mainly the case for errors falling under the same HTTP status code, e.g. multiple errors related to a 400.

Errors related to authentication and authorization also conform to the ↗ OAuth2 specification . They additionally contain the field error and, if available, the field error_description.

{
    "statusCode": 401,
    "message": "This endpoint requires an access token. You can get one from the authorization server.",
    "errors": [{
      "code": "access_denied",
      "message": "This endpoint requires an access token. You can get one from the authorization server."
    }],
    "error": "access_denied",
    "error_description": "This endpoint requires an access token. You can get one from the authorization server."
}

Also note that error codes defined by the OAuth spec are not written in camelCase.

General

500 Internal Server Error

The following general error codes can appear in responses with the HTTP status code 500:

503 Service Unavailable

The following general error codes can appear in responses with the HTTP status code 503:

404 Not Found

The following general error codes can appear in responses with the HTTP status code 404:

400 Bad Request

The following general error codes can appear in responses with the HTTP status code 400:

409 Conflict

The following general error codes can appear in responses with the HTTP status code 409:

Products

400 Bad Request

The following product-specific error codes can appear in responses with the HTTP status code 400:

Orders

400 Bad Request

The following order-specific error codes can appear in responses with the HTTP status code 400:

Customers

400 Bad Request

The following customer-specific error codes can appear in responses with the HTTP status code 400:

comments powered by Disqus