Skip to main content

​
Error Response Format

All errors return a JSON response with an error type and message: 
{
  "error": "Error Type",
  "message": "Detailed error description"
}

​
HTTP Status Codes

CodeNameDescription
200OKRequest successful
400Bad RequestInvalid parameters or malformed request
401UnauthorizedMissing or invalid API key
404Not FoundVessel or resource not found
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer-side error

​
Common Errors

​
400 Bad Request

Invalid parameters in your request: 
{
  "error": "Bad Request",
  "message": "Invalid IMO/MMSI format. Expected 7-digit IMO or 9-digit MMSI."
}
Solutions:
  • Verify IMO numbers are 7 digits
  • Verify MMSI numbers are 9 digits
  • Check date formats match ISO 8601
  • Ensure required parameters are provided

​
401 Unauthorized

Authentication failed: 
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}
Solutions:
  • Include the x-api-key header
  • Verify your API key is correct
  • Check if your key has been revoked

​
404 Not Found

Vessel or resource doesn’t exist: 
{
  "error": "Not Found",
  "message": "No vessel found with IMO 0000000"
}
Solutions:
  • Verify the IMO/MMSI number is correct
  • Check if the vessel is still active
  • Try searching by name first

​
429 Rate Limited

Too many requests: 
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please wait before making more requests."
}
Solutions:
  • Implement exponential backoff
  • Cache responses when possible
  • Use bulk endpoints

​
Error Handling Example

import requests
import time

def make_api_request(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code == 200:
            return response.json()

        elif response.status_code == 400:
            error = response.json()
            raise ValueError(f"Invalid request: {error['message']}")

        elif response.status_code == 401:
            raise PermissionError("Invalid or missing API key")

        elif response.status_code == 404:
            return None  # Vessel not found

        elif response.status_code == 429:
            wait_time = 2 ** attempt
            time.sleep(wait_time)
            continue

        else:
            raise Exception(f"API error: {response.status_code}")

    raise Exception("Max retries exceeded")

​
Debugging Tips

  1. Check the response body - Error messages provide specific details
  2. Verify parameters - Use the API playground to test requests
  3. Check your credits - Some errors may be due to insufficient credits
  4. Review rate limits - Check X-RateLimit-Remaining header