> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datadocked.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> Understanding API errors and how to handle them

## Error Response Format

All errors return a JSON response with an error type and message:

```json theme={null}
{
  "error": "Error Type",
  "message": "Detailed error description"
}
```

## HTTP Status Codes

| Code | Name                  | Description                             |
| ---- | --------------------- | --------------------------------------- |
| 200  | OK                    | Request successful                      |
| 400  | Bad Request           | Invalid parameters or malformed request |
| 401  | Unauthorized          | Missing or invalid API key              |
| 404  | Not Found             | Vessel or resource not found            |
| 429  | Too Many Requests     | Rate limit exceeded                     |
| 500  | Internal Server Error | Server-side error                       |

## Common Errors

### 400 Bad Request

Invalid parameters in your request:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

```python theme={null}
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