Response handling

Response codes

The Shipper API supports default HTTP response codes:

Status codeResponse type
2xxSuccessful response
3xxRedirection
4xxClient/validation errors
5xxServer errors

Response body format

The API generally returns a JSON response similar to JSend.

Single object

1
2
3
4
5
6
7
8

{
    "status": "success",
    "data": {
        "object": {
            ...
        }
    }
}

For example, a response with a load offer:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

{
  "status": "success",
  "data": {
    "object": {
      "created_at": "2018-05-30T10:35:01.051+0000",
      "changed_at": "2018-05-30T10:42:20.805+0000",
      "status": "canceled",
      "carrier_email": "[email protected]",
      "carrier_phone": "202-555-0104",
      "carrier_name": "Acme Corporation",
      "carrier_contact_name": "Arnold Weber",
      "driver_name": "Bernard",
      "driver_phone": "202-555-0181",
      "carrier_guid": "532933b06a5a472ba22657bd9ea2375e",
      "guid": "6c827135-9667-41cb-8a76-d58c9c8f6947",
      "active": true
    }
  }
}

List of objects

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "status": "success",
  "data": {
    "objects": [{}, {}, ...{}],
    "pagination": {
      "total_pages": 0,
      "total_objects": 0,
      "limit": 0,
      "page": 0
    }
  }
}

The list of load offers:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

{
  "status": "success",
  "data": {
    "objects": [
      {
        "created_at": "2018-05-30T10:35:01.051+0000",
        "changed_at": "2018-05-30T10:42:20.805+0000",
        "status": "canceled",
        "carrier_email": "[email protected]",
        "carrier_phone": "202-555-0104",
        "carrier_name": "Acme Corporation",
        "carrier_contact_name": "Arnold Weber",
        "driver_name": "Bernard",
        "driver_phone": "202-555-0181",
        "carrier_guid": "7d57730b-384e-4f46-827e-afa3abbda248",
        "guid": "78e0c452-3cac-4690-808b-0e705a324797",
        "active": true
      },
      {
        "created_at": "2018-05-31T11:39:01.051+0000",
        "changed_at": "2018-05-31T15:42:20.805+0000",
        "status": "accepted",
        "carrier_email": "[email protected]",
        "carrier_phone": "202-555-0105",
        "carrier_name": "Hooli",
        "carrier_contact_name": "Gavin Belson",
        "driver_name": "Nelson Bighetti",
        "driver_phone": "202-555-0108",
        "carrier_guid": "3d7c4ce2-7135-4482-a3dd-759833ca7b82",
        "guid": "ae332f7f-ef4e-4e91-92ac-d8efbd33e37d",
        "active": true
      }
    ],
    "pagination": {
      "total_pages": 1,
      "total_objects": 2,
      "limit": 20,
      "page": 0
    }
  }
}

See also pagination and sorting.

Error handling

The API returns a standard 4xx HTTP validation response when a request has validation issues. For authentication issues the API just returns 401 UNAUTHORIZED without the response body. In other cases the API returns more descriptive response with more details:

For example, when a requested load offer isn’t found the response status is 404 NOT FOUND and the body is:

1
2
3
4
5
6
7
8

{
  "status": "fail",
  "data": {
    "message": "Offer not found",
    "error_id": "OFFER_NOT_FOUND",
    "details": null
  }
}