Skip to main content

​
Error Handling

The Artos API returns standard HTTP status codes with detailed error messages. This guide explains how to handle common errors.

​
HTTP Status Codes

StatusCodeDescription
Success200Request succeeded (GET, PUT)
Created201Resource created (POST)
Accepted202Request accepted for async processing
Bad Request400Invalid parameters or validation error
Unauthorized401Missing or invalid authentication
Forbidden403Insufficient permissions
Not Found404Resource does not exist
Unprocessable Entity422Request validation error
Internal Server Error500Server-side error

​
Error Response Format

All error responses return a JSON object with error details: 
{
  "detail": "Error message describing what went wrong"
}
For some endpoints, errors may include additional context: 
{
  "error": "error_code",
  "error_description": "Detailed description",
  "details": {
    "field": "value",
    "suggestion": "How to fix it"
  }
}

​
Common Errors

​
401 Unauthorized - Missing Token

Error: 
{
  "detail": "Not authenticated"
}
Cause: Authorization header is missing or empty Solution: Include a valid Bearer token: 
curl -X GET "https://api.artosai.com/api/v1/templates/" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
401 Unauthorized - Invalid Token

Error: 
{
  "detail": "Invalid authentication credentials"
}
Cause:
  • Token is malformed
  • Token has expired
  • Token was revoked
  • Token is for a different organization
Solution:
  1. Verify token format is correct
  2. Obtain a fresh token from your administrator
  3. Check token hasn’t been revoked
  4. Verify token is for the correct environment

​
403 Forbidden - Wrong Organization

Error: 
{
  "detail": "User has no organization or not authorized"
}
Cause:
  • User’s token doesn’t have an organization
  • Resource belongs to a different organization
  • User is not member of the organization
Solution: Contact your organization administrator to verify your account setup

​
404 Not Found - Resource Missing

Error: 
{
  "detail": "Document not found or not accessible"
}
Cause:
  • Resource ID is incorrect
  • Resource has been deleted
  • Resource belongs to a different organization
Solution:
  1. Verify the resource ID is correct
  2. Check that the resource exists in your organization
  3. List available resources to find the correct ID

​
400 Bad Request - Validation Error

Error: 
{
  "detail": "Missing required parameter: document_type"
}
Cause: Request is missing required fields or has invalid values Solution:
  1. Check the API documentation for required fields
  2. Verify all required parameters are included
  3. Ensure values match the correct type and format

​
422 Unprocessable Entity - Invalid Structure

Error: 
{
  "detail": "Request validation error"
}
Cause: Request structure is invalid or doesn’t match schema Solution:
  1. Review the request body format
  2. Ensure nested objects are properly structured
  3. Validate against the OpenAPI specification

​
500 Internal Server Error

Error: 
{
  "detail": "Internal server error"
}
Cause: Server-side processing error Solution:
  1. Retry the request after a brief delay
  2. Check the Artos status page
  3. Contact support if the error persists

​
Error Handling Best Practices

​
1. Implement Exponential Backoff

Retry failed requests with increasing delays: 
import time
import requests

def make_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.get(url, headers=headers)
            if response.status_code == 200:
                return response.json()
            elif response.status_code >= 500:
                # Server error - retry
                wait = 2 ** attempt  # 1s, 2s, 4s
                print(f"Retrying in {wait}s...")
                time.sleep(wait)
            else:
                # Client error - don't retry
                print(f"Error: {response.status_code}")
                print(response.json())
                break
        except requests.exceptions.RequestException as e:
            print(f"Request failed: {e}")
            wait = 2 ** attempt
            time.sleep(wait)

    raise Exception("Max retries exceeded")

​
2. Check Status Codes

Always check the response status before processing: 
import requests

response = requests.get(
    "https://api.artosai.com/api/v1/documents/doc-id",
    headers={"Authorization": f"Bearer {token}"}
)

if response.status_code == 200:
    document = response.json()
    print(f"Document: {document}")
elif response.status_code == 404:
    print("Document not found")
elif response.status_code == 401:
    print("Authentication failed")
else:
    print(f"Error: {response.status_code}")
    print(response.json())

​
3. Handle Async Operations

For async operations (202 responses), implement status polling: 
import time

# Request document generation
response = requests.post(
    "https://api.artosai.com/api/v1/documents/generate",
    headers=headers,
    json=payload
)

if response.status_code == 202:
    task_id = response.json()['task_id']

    # Poll status
    while True:
        status = requests.get(
            f"https://api.artosai.com/api/v1/documents/status/{task_id}",
            headers=headers
        ).json()

        print(f"Status: {status['status']}")

        if status['status'] == 'Complete':
            print("Done!")
            break
        elif status['status'] == 'Failed':
            print(f"Error: {status['error']}")
            break

        time.sleep(5)

​
4. Validate Input

Validate input before sending requests: 
def generate_document(payload):
    # Check required fields
    required = [
        'document_type',
        'file_paths',
        'document_set_key',
        'document_set_name',
        'generic_mrt_id',
        'output_name'
    ]

    for field in required:
        if field not in payload:
            raise ValueError(f"Missing required field: {field}")

    # Check types
    if not isinstance(payload['file_paths'], list):
        raise ValueError("file_paths must be an array")

    if len(payload['file_paths']) == 0:
        raise ValueError("file_paths cannot be empty")

    # Make request
    return requests.post(
        "https://api.artosai.com/api/v1/documents/generate",
        headers=headers,
        json=payload
    )

​
5. Log Errors for Debugging

Log error details for troubleshooting: 
import logging
import json

logger = logging.getLogger(__name__)

try:
    response = requests.get(url, headers=headers)
    response.raise_for_status()
except requests.exceptions.HTTPError as e:
    error_data = e.response.json()
    logger.error(
        "API request failed",
        extra={
            "status_code": e.response.status_code,
            "url": e.response.url,
            "error": error_data,
            "request_body": payload
        }
    )
    raise

​
Debugging Tips

​
1. Enable Debug Logging

import logging
import requests

logging.basicConfig(level=logging.DEBUG)
logging.getLogger("urllib3").setLevel(logging.DEBUG)

response = requests.get(url, headers=headers)

​
2. Check Token Validity

Verify your token hasn’t expired: 
# Tokens are JWT - you can decode them at jwt.io
# Or implement validation in your code

import jwt

token = "your_token"
try:
    decoded = jwt.decode(token, options={"verify_signature": False})
    print(f"Token expires at: {decoded.get('exp')}")
except jwt.InvalidTokenError:
    print("Token is invalid")

​
3. Test with curl

Use curl for quick testing: 
# Test authentication
curl -i -H "Authorization: Bearer $TOKEN" \
  https://api.artosai.com/api/v1/templates/

# Check response headers
curl -v -H "Authorization: Bearer $TOKEN" \
  https://api.artosai.com/api/v1/templates/

# Pretty-print JSON
curl -s -H "Authorization: Bearer $TOKEN" \
  https://api.artosai.com/api/v1/templates/ | jq '.'

​
4. Review OpenAPI Spec

Check the OpenAPI specification at /api-reference/openapi-v1.json for:
  • Required parameters
  • Expected response formats
  • Status codes for each endpoint

​
Support

If you encounter persistent errors:
  1. Check the documentation - Review endpoint documentation for parameters
  2. Verify your token - Contact your administrator if token issues
  3. Check system status - Look for maintenance or outages
  4. Enable debug logging - Get detailed request/response information
  5. Contact support - Reach out to [email protected] with error details