Skip to main content

​
Error Codes

The Voyager API uses standard HTTP status codes and returns detailed error messages to help you understand what went wrong.

​
HTTP Status Codes

CodeStatusDescription
200OKRequest succeeded
201CreatedResource created successfully
204No ContentRequest succeeded, no response body
400Bad RequestInvalid request parameters
401UnauthorizedAuthentication required or invalid
403ForbiddenInsufficient permissions
404Not FoundResource not found
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer error

​
Error Response Format

All error responses follow this format: 
{
  "detail": "Error message describing what went wrong",
  "code": "ERROR_CODE",
  "field": "field_name"  // Optional, for field-level errors
}

​
Common Errors

​
400 Bad Request

Invalid request parameters or malformed request body. Example: 
{
  "detail": "Invalid project ID format",
  "code": "INVALID_UUID"
}
Common causes:
  • Invalid UUID format
  • Missing required fields
  • Invalid parameter values

​
401 Unauthorized

Authentication failed or token expired. Example: 
{
  "detail": "Invalid token."
}
Solutions:
  • Verify your credentials
  • Re-authenticate to get a new token
  • Check token expiration

​
403 Forbidden

Valid authentication but insufficient permissions. Example: 
{
  "detail": "You do not have permission to perform this action.",
  "code": "PERMISSION_DENIED"
}
Common causes:
  • Missing required capability (e.g., PROJECT_DATA_EXPORT)
  • Workspace-level restrictions
  • Project-level access restrictions
Solutions:
  • Contact support@lumafield.com to request capabilities
  • Verify workspace membership
  • Check project access permissions

​
404 Not Found

Resource doesn’t exist or was deleted. Example: 
{
  "detail": "Project not found."
}
Solutions:
  • Verify the resource ID
  • Check if the resource was deleted
  • Ensure you have access to the resource

​
429 Too Many Requests

Rate limit exceeded. Example: 
{
  "detail": "Rate limit exceeded. Please try again later.",
  "code": "RATE_LIMIT_EXCEEDED"
}
Solutions:
  • Implement exponential backoff
  • Add delays between requests
  • Contact support for higher limits

​
Field-Level Validation Errors

Some endpoints return field-specific errors: 
{
  "detail": "Validation failed",
  "errors": {
    "email": ["This field is required."],
    "password": ["Password must be at least 8 characters."]
  }
}

​
Error Handling Best Practices

​
1. Always Check Status Codes

response = requests.get(url, headers=headers)
if response.status_code == 200:
    data = response.json()
elif response.status_code == 401:
    # Re-authenticate
    token = authenticate()
elif response.status_code == 403:
    # Check permissions
    print("Insufficient permissions")
else:
    response.raise_for_status()

​
2. Parse Error Messages

try:
    response.raise_for_status()
except requests.exceptions.HTTPError as e:
    error_data = e.response.json()
    print(f"Error: {error_data.get('detail')}")
    if 'code' in error_data:
        print(f"Code: {error_data['code']}")

​
3. Implement Retry Logic

import time

def make_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.get(url, headers=headers)
            response.raise_for_status()
            return response.json()
        except requests.exceptions.HTTPError as e:
            if e.response.status_code == 429:
                wait_time = 2 ** attempt  # Exponential backoff
                time.sleep(wait_time)
                continue
            raise
    raise Exception("Max retries exceeded")

​
Next Steps