New Zealand Couriers Knowledge

60 Years Keeping New Zealand Business Moving Help Centre

    New Zealand Couriers Knowledge

    60 Years Keeping New Zealand Business Moving Help Centre

    Common Header & Error Codes

    Updated: 20 Oct 25

    Common Headers & Request Structure

    Every Freightways API request should include the following headers:

    Header Required Description Example
    Content-Type ✅ Specifies the media type of the request body. Must be application/json. application/json
    Accept ✅ Determines the response format. Always application/json. application/json
    Authorization ✅ Used when authenticating via OAuth2 Bearer tokens. Bearer eyJhbGci...

    Example request headers:

     
    POST /v1/consignments HTTP/1.1 Host: customer-integration.ep-sandbox.freightways.co.nz Content-Type: application/json Accept: application/json Authorization: Bearer eyJraWQiOiJDQ2h**

    Common Error Response Format

    All errors follow a consistent structure:

     
    {
    "errors": {
        "REQUEST_VALIDATION_ERROR": [
            "Label format must be PDF"
        ]
    },
    "type": "https://httpstatuses.com/400",
    "title": "REQUEST_VALIDATION_ERROR",
    "status": 400,
    "detail": "Please check the errors collection if available to help identify which request data is incorrect",
    "instance": "/customer-integration/v1/carriers/NZCouriers/customers/1234567/consignments/CU..XYZ123.A.1234567.1/labels?format=ZPL&size=FreThermal-174x100",
    "correlationId": "65ff0a9b-35ee-49cf-8133-a8d0771a75a2"
}
    Field Type Description
    errors array Error details
    type string HTTP status code
    title string human-readable summary of the problem type
    status string HTTP status code
    detail string A human-readable explanation specific to this occurrence of the problem.
    instance string endpoint utilised
    correlationId string error Id - helps with troubleshooting

    Common HTTP Status Codes:

    Code Description
    200 Success
    201 Resource created successfully
    400 Invalid request format or validation error
    401 Unauthorized – missing or invalid credentials
    403 Forbidden – insufficient permissions
    404 Resource not found
    429 Rate limit exceeded
    500 Internal server error

    Did this article answer your question?

    Related Articles

    Dangerous Goods Policy

    Coverage options for international sending

    Sending to a Residential Delivery Zone

    Popular Articles

    Domestic Delivery Updates

    What time will my parcel be delivered? Expected delivery time

    Terms and Conditions for sending within New Zealand

    Missing, Lost or Damaged Deliveries

    Can't find the answer to your question?

    Suggest an article