Error Handling

The Mentium TMS API uses standard HTTP status codes and returns detailed error information.

Error Response Format

All errors return a consistent JSON structure:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": [
      {
        "field": "zip_code",
        "message": "zip_code is required"
      }
    ]
  }
}

HTTP Status Codes

Status Code	Description
200	Success
201	Created - Resource successfully created
204	No Content - Successful deletion
400	Bad Request - Invalid request data
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
409	Conflict - Resource already exists
422	Unprocessable Entity - Validation failed
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Something went wrong

Common Error Codes

Authentication Errors

UNAUTHORIZED

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Solution: Check that your API key is correct and included in the X-API-Key header.

FORBIDDEN

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key does not have the required scope: write:loads"
  }
}

Solution: Create an API key with the required scopes.

Validation Errors

VALIDATION_ERROR

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": [
      { "field": "email", "message": "Invalid email format" },
      { "field": "zip_code", "message": "zip_code is required" }
    ]
  }
}

Solution: Fix the validation errors listed in the details array.

Resource Errors

NOT_FOUND

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Location with id '123' not found"
  }
}

Solution: Verify the resource ID exists and belongs to your organization.

CONFLICT

{
  "error": {
    "code": "CONFLICT",
    "message": "A location with this external_id already exists"
  }
}

Solution: Use a unique identifier or update the existing resource.

Error Handling Example

Python

import requests

def create_location(api_key, location_data):
    response = requests.post(
        "https://api.mentium.io/v2/tms-api/locations",
        headers={"X-API-Key": api_key, "Content-Type": "application/json"},
        json=location_data
    )
    
    if response.status_code == 201:
        return response.json()
    
    error = response.json().get("error", {})
    
    if response.status_code == 401:
        raise AuthenticationError(error.get("message"))
    elif response.status_code == 422:
        raise ValidationError(error.get("details", []))
    elif response.status_code == 429:
        retry_after = error.get("retry_after", 60)
        raise RateLimitError(f"Rate limited. Retry after {retry_after}s")
    else:
        raise APIError(error.get("message", "Unknown error"))

JavaScript

async function createLocation(apiKey, locationData) {
  const response = await fetch("https://api.mentium.io/v2/tms-api/locations", {
    method: "POST",
    headers: {
      "X-API-Key": apiKey,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(locationData)
  });
  
  if (response.status === 201) {
    return response.json();
  }
  
  const { error } = await response.json();
  
  switch (response.status) {
    case 401:
      throw new Error(`Authentication failed: ${error.message}`);
    case 422:
      throw new Error(`Validation failed: ${JSON.stringify(error.details)}`);
    case 429:
      throw new Error(`Rate limited. Retry after ${error.retry_after}s`);
    default:
      throw new Error(error.message || "Unknown error");
  }
}