HTTP Errors

Searoutes' APIs follow the HTTP response status codes, which indicate whether a specific HTTP request has been successfully completed. Below a summary of the most common codes you'll find in our responses:

200OK. Everything worked as expected.
400Bad Request. The request was unacceptable, often due to missing a required parameter.
401Unauthorized. No valid API key provided.
403Forbidden. The API key doesn't have permissions to perform the request.
404Not Found. The requested resource doesn't exist.
429Too Many Requests. Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504Server Errors. Something went wrong on Searoutes' end.

API Error Codes

In case of Bad Requests (400 status code) and Not Found (404 status code) responses, an error code is returned in the response to give more details. These error codes are listed below and can be used to map custom error messages.

Error codeDescription / message
1000Default error code when a ressource has not been found.
1010Port with a given name has not been found.
1020Route has not been found.
1031Vessel with the given IMO has not been found.
1032Vessel with the given name has not been found.
1033Vessel Tracking info has not been found (real time position or ETA for instance)
1040Location has not been found.
1050Airport has not been found.
1060Area has not been found.
1071Carrier with the given SCAC has not been found.
1072Carrier with the given ID has not been found.
1080Rail region has not been found - from/to should be in the same region.
1090Road region has not been found - from/to should be in the same region.
1110Itinerary for the given parameters has not been found.
1121Service with the given name has not been found.
1122Service with the given ID has not been found.
2000Default error code when an illegal argument has been passed.
2001Default error when a parameter is missing.
2002Parameter name must be given to search for a service.
2003Either parameter SCAC or name must be given to search for a carrier.
2010Unknown container size.
2020Coordinates or locode is required.
2030CO2 values for rail for the combination of parameters cannot be calculated.
2040CO2 values for road for the combination of parameters cannot be calculated.
2050CO2 for carrier cannot be calculated.
2060Could not find appropriate size of truck.
2070Illegal list of sizes.
2080Inland waters CO2 can not be computed.
2090Wrong value or format of date.
2110Illegal vessel (invalid wrong type of vessel for instance)
3000Default error code when a parameter is not valid.
3010'aircraftType' parameter is invalid.
3020'weight' parameter is invalid.
3030'loadCharacteristics' parameter is invalid.
3040'size' parameter is invalid.
3050'from' / 'to' is invalid.
3060'aircraftIATA' parameter is invalid.
3070'containerSize' parameter is invalid.
3080'fuel' parameter is invalid.
3090'carrierId' parameter is invalid.
3100'fromIATA' /' toIATA' parameter is invalid.
3110'fromLocode' / 'toLocode' parameter is invalid.
3120'country' parameter is invalid.
3130'postal' parameter is invalid.
3140'vesselImo' parameter is invalid.
3150'vesselName' parameter is invalid.
3160Area name ('name' parameter) is invalid.
3170'nameOrLocode' path variable is invalid.
3180'nameOrLocodeOrIata' path variable is invalid.
3190Coordinates have invalid format.
3200'volume' parameter is invalid.
3210From and/or to are in a blocked area.
3220locationType is invalid.
3230From and/or to are in a forbidden area (military base for example).
3240Illegal hash format.
3250Illegal carrier scac.
3260'vesselType' parameter is invalid.
3300'containerSizeTypeCode' value is invalid.
3310'containerType' value is invalid.
3320Invalid date format.
3330Invalid combination of parameters for historical search.
3340From and to locodes must be different.
4000Default error code when the request is invalid (including parsing errors).
4001Type is invalid.
4002JSON parse error.
5000Default error code when a service is not available.
5010The geocoding service is unavailable.
5020The AIS service is unavailable.
5030The CO2 calculation service is unavailable
5040The route calculation service is unavailable.