Error Handling in CargoFP API

All errors from the CargoFP API follow a standard JSON structure. Errors are grouped into Validation Errors, Client Errors, and Server Errors.

Error Response Structure

{
  "type": "<error_type>",
  "errors": [
    {
      "code": "<error_code>",
      "detail": "<error_description>",
      "attr": "<request_attribute>"
    }
  ]
}

type can be validation_error, client_error, or server_error
errors is an array of error objects
code is a short error identifier
detail is a descriptive message
attr is the field associated with the error (or non_field_errors for global issues)

Example: Unknown Port

{
  "type": "validation_error",
  "errors": [
    {
      "code": "unknown_port",
      "detail": "Port is unknown.",
      "attr": "departure_port"
    }
  ]
}

Error Types & Details

Validation Errors

Code	Detail	Attribute
`required`	Field is required	Any field
`min_value`	Must be ≥ 0	`cargo_weight_mt`
`unknown_port`	Port is unknown	`departure_port_code`, `arrival_port_code`, `departure_port_name`, `arrival_port_name`
`same_ports`	Departure and arrival cannot be the same	`non_field_errors`
`arrival_before_departure`	Arrival must be after departure	`non_field_errors`
`ship_not_available`	Ship not in database	`non_field_errors`
`ship_data_not_available`	Missing required ship data	`non_field_errors`
`ship_type_not_accepted`	Ship type not allowed	`non_field_errors`
`new_ship`	Ship too new for emission calculation	`non_field_errors`
`emission_data_not_available`	No emissions data for voyage	`non_field_errors`
`distance_not_available`	Distance between ports not available	`non_field_errors`
`incorrect_number_of_digits`	IMO number must have 7 digits	`imo_number`
`invalid_imo_number`	Check of the IMO number via check mechanism resulted in invalid	`imo_number`

Client Errors

HTTP Code	Code	Detail
400	`parse_error`	Malformed request
401	`authentication_failed`	Invalid credentials
401	`not_authenticated`	No auth token provided
403	`permission_denied`	Not allowed to access resource
404	`not_found`	Resource not found
405	`method_not_allowed`	HTTP method not allowed
406	`not_acceptable`	Accept header not satisfied
415	`unsupported_media_type`	Only `application/json` is supported
429	`throttled`	Rate limit exceeded

Server Errors

HTTP Code	Code	Detail
500	`error`	Internal server error
503	`service_unavailable`	Service is temporarily unavailable