Errors

Learn about error responses and status codes from the Trakkr API

The Trakkr API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information, and codes in the 5xx range indicate an error with our servers.

Error Response Format

All error responses follow this format:

{
  "error": "Error title",
  "errors": ["Detailed error message"]
}

HTTP Status Codes

Status Code	Description
200	Success - The request was successful
400	Bad Request - The request was invalid
401	Unauthorized - Missing or invalid API key
403	Forbidden - Valid API key but insufficient permissions
500	Internal Server Error - Something went wrong on our end

Common Error Responses

400 Bad Request

Missing Required Parameter

{
  "error": "Missing required parameter: brand",
  "errors": ["brand parameter is required"]
}

Invalid Breakdown Format

{
  "error": "Invalid breakdown parameter format",
  "errors": ["breakdown must be a valid JSON array"]
}

Invalid Breakdown Values

{
  "error": "Invalid breakdown values",
  "errors": ["Invalid breakdown values: ['invalid']. Valid values are: ['model', 'prompt']"]
}

Invalid Date Format

{
  "error": "Invalid start_date format",
  "errors": ["start_date must be in YYYY-MM-DD format"]
}

Date Range Too Large

{
  "error": "Date range too large",
  "errors": ["The total date range cannot exceed 90 days"]
}

401 Unauthorized

Missing API Key

{
  "error": "Missing API key",
  "errors": ["API key must be provided in the Authorization header as 'Bearer <api_key>'"]
}

403 Forbidden

Invalid API Key

{
  "error": "Invalid API key",
  "errors": ["No accounts found for this API key"]
}

Brand Access Denied

{
  "error": "Brand access denied",
  "errors": ["You do not have access to this brand"]
}

500 Internal Server Error

Authentication Error

{
  "error": "Authentication error",
  "errors": ["Could not validate API key against database"]
}

Date Range Validation Error

{
  "error": "Date range validation error",
  "errors": ["Could not validate date range: invalid date format"]
}

General Server Error

{
  "error": "Internal server error",
  "errors": ["An unexpected error occurred: [error details]"]
}

Handling Errors

JavaScript Example

try {
  const response = await fetch('https://api.trakkr.ai/get-scores', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      brand: '0000000000000x000000000000000000',
      breakdown: ['model']
    })
  });

  if (!response.ok) {
    const errorData = await response.json();
    console.error(`Error ${response.status}:`, errorData.error);
    console.error('Details:', errorData.errors);
    return;
  }

  const data = await response.json();
  console.log('Success:', data);
} catch (error) {
  console.error('Network error:', error);
}

Python Example

import requests

try:
    response = requests.post(
        'https://api.trakkr.ai/get-scores',
        headers={
            'Authorization': 'Bearer YOUR_API_KEY',
            'Content-Type': 'application/json'
        },
        json={
            'brand': '0000000000000x000000000000000000',
            'breakdown': ['model']
        }
    )
    
    if response.status_code != 200:
        error_data = response.json()
        print(f"Error {response.status_code}: {error_data.get('error')}")
        print(f"Details: {error_data.get('errors')}")
    else:
        data = response.json()
        print('Success:', data)
        
except requests.exceptions.RequestException as e:
    print(f"Network error: {e}")

Error Handling Best Practices

1. Check status codes: Always check the HTTP status code before processing the response
2. Parse error messages: Extract both the error title and detailed messages
3. Handle network errors: Catch and handle network-level exceptions
4. Log errors: Log error details for debugging purposes
5. Retry logic: Consider implementing retry logic for 5xx errors
6. User feedback: Provide meaningful error messages to end users

Rate Limiting

While the API doesn’t have strict rate limits, we recommend:

• Making reasonable numbers of requests
• Implementing exponential backoff for retries
• Caching responses when appropriate
• Avoiding rapid-fire requests

Need help debugging? If you’re getting unexpected errors, check our authentication guide or contact support with the full error response.