V1 and V2 errors and status codes

This page documents the HTTP status codes and the response formats you encounter when you call the V1 and V2 APIs. Successful responses and error responses use different shapes, so it helps to know both before you write error handling.

HTTP status codes

The API uses a small subset of standard HTTP status codes, grouped by class:

On search endpoints, 422 means the search itself is invalid, and 428 means the search matches too many records to sort. See Filtering and search for the exact rules.

Successful response format

A successful response wraps its results in a data list. A single record still comes back as a list with one item, and a request that matches nothing returns an empty list.

{
  "data": [
    {
      "id": "123456789012345678901234",
      "filename": "example.pdf",
      "file_size": 30358
    }
  ]
}

{
  "data": []
}

Search responses add a pagination object next to data. See Pagination.

Error response format

When an operation fails, the response contains an error object instead of data. The error object has these fields:

Each entry in errors has two fields:

A simple error carries only msg:

{
  "error": {
    "msg": "Missing Authorization Header"
  }
}

A detailed error lists each field that failed validation:

{
  "error": {
    "msg": "product data validation failed",
    "errors": [
      {
        "field": "some_non-existing_attribute_to_patch",
        "msg": "label does not exist"
      },
      {
        "field": "some_decimal_number_attribute_to_patch_using_wrong_number_format",
        "msg": "Not a valid decimal value. Format must be: ."
      }
    ]
  }
}