Errors

All requests and responses are validated against the OpenAPI spec.

Requests that have been successfully processed return 2xx HTTP status codes.

Most types of error status codes (HTTP 400, 401, 403 etc.) contain a machine-friendly error_code and a human-readable error message.

Notable exceptions:

• HTTP 404: resource not found, we have nothing to add
• HTTP 500: we were not expecting errors therefore we have nothing to add

You can find a list of error_codes in the OpenAPI spec.

Error codes are defined in a way that balances precision (supporting handling specific error conditions) with redundancy (if we wanted to define an error code for every single thing the list would be huge and handling similar errors would be very tedious).

Responses contain a CF-Ray header that can be reported to Lune to help with tracking down issues.

How to handle errors

• A response with an error code – handle according to the response’s error message
• No error code and HTTP 5xx – should not happen, unexpected error. Safe to retry
• Connection error or timeout error – feel free to retry the same request
  • Some API endpoints, like creating an order, employ safety mechanisms (idempotency keys) to prevent creating redundant orders.

Example

{
  "error": {
    "error_code": "order_quantity_invalid"
    "message": "Order quantity must be positive.",
  }
}

Example

{
  "error": {
    "error_code": "validation_error",
    "message": "Provided data does not match the defined schema.: .body.shipment.mass.amount should match pattern "^[0-9]+(\.[0-9]+)?$", .body.shipment.containers should have required property 'containers', .body.shipment.mass.amount should match pattern "^[0-9]+(\.[0-9]+)?$", .body.shipment should match exactly one schema in oneOf"
  }
}

Example

{
  "error": {
    "error_code": "address_not_found",
    "message": "The source address could not be found"
  }
}