2. Responses

As stated earlier data is usually sent back in JSON format. Exceptions to this rule are shipment label, invoice and CSV export. Shipment label and invoice are sent back in PDF format while CSV export is sent back in CSV format. Typically, a response will have a response body. Exceptions are DELETE requests which will only contain a status code (204) indicating success. A failed request with a 4xx status code will always send back a response body with the error description. A failed request with a 5xx status code will probably mean you've hit a snag in our API. We try to monitor these kinds of errors, but if you keep having trouble... Don't hesitate to reach out!

# 2.A HTTP statuses

HTTP status codes are used to indicate success or failure of a request. Here's a list of supported status codes. For a more comprehensive list of HTTP status codes visit Wikipedia or W3C.

Example of a HTTP 200 OK in our API (you can try this in your browser, then you know our API is online).

Request:

GET https://api.myparcel.nl/
Request Headers (example):
GET / HTTP/1.1
Host: api.myparcel.nl
Connection: keep-alive
Pragma: no-cache
Cache-Control: no-cache
Upgrade-Insecure-Requests: 1
Accept-Encoding: gzip, deflate, sdch, br

Response:

{
  "title":"MyParcel API",
  "status":"OK"
}
Response Headers (example!)
<Http code=200 />
Date: Tue, 31 Jan 2017 13:37:00 GMT
Content-Type: application/json;charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive

# 2.A.I 2xx

Used for successful requests. Successful requests may contain a response body e.g. object id of new object or none when modifying an existing object.

# 2.A.I 200 - OK

This status code is used for successful requests that have a response body.

# 2.A.I 202 - Accepted

This status code is used for requests that have been received successfully and will be processed at a later time. This is mostly used for processing shipments and addresses CSV.

# 2.A.I 204 - No Content

This status is used primarily for DELETE requests.

# 2.A.II 3xx

# 2.A.II 304 - Not Modified

This status is used by the server when the resource is the same as the one the client has.

# 2.A.III 4xx

Used for failed requests. Failed requests always contain a response body with the error description.

# 2.A.III 400 - Bad Request

When the request received is malformed.

# 2.A.III 401 - Unauthorized

No credentials have been sent with the request, or the wrong credentials are sent. Tip: check if the API key is properly attached in the header:

Authorization: bearer BASE64_ENCODED_API_KEY

# 2.A.III 402 - Payment Required

When payment is required. An Invoice object may be sent with this response.

# 2.A.III 403 - Forbidden

When the given credentials are not authorized to perform a certain action.

# 2.A.III 404 - Not Found

When a resource cannot be found.

# 2.A.III 405 - Method not allowed

When you used a method on an endpoint that is either not supported or not allowed for the given credentials.

# 2.A.III 406 - Not acceptable

When the client requests a given format for a resource that is not supported.

# 2.A.III 415 - Unsupported media type

When the client specifies a Content-Type in the request that is not supported.

# 2.A.III 422 - Unprocessable Entity

When the client sends a request object with invalid data. The error message will specify what's wrong with the request or the data sent to the API.

# 2.A.III 409 - Conflict

When the client request conflicts with the current state of the resource.

# 2.A.IV 5xx

Used for server-side errors. This happens when we (i.e. MyParcel.nl / the API) are having problems.