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

Status	Code	Description
Success	200	Request succeeded (GET, PUT)
Created	201	Resource created (POST)
Accepted	202	Request accepted for async processing
Bad Request	400	Invalid parameters or validation error
Unauthorized	401	Missing or invalid authentication
Forbidden	403	Insufficient permissions
Not Found	404	Resource does not exist
Unprocessable Entity	422	Request validation error
Internal Server Error	500	Server-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:

Verify token format is correct
Obtain a fresh token from your administrator
Check token hasn’t been revoked
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:

Verify the resource ID is correct
Check that the resource exists in your organization
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:

Check the API documentation for required fields
Verify all required parameters are included
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:

Review the request body format
Ensure nested objects are properly structured
Validate against the OpenAPI specification

500 Internal Server Error

Error:

{
  "detail": "Internal server error"
}

Cause: Server-side processing error Solution:

Retry the request after a brief delay
Check the Artos status page
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:

Check the documentation - Review endpoint documentation for parameters
Verify your token - Contact your administrator if token issues
Check system status - Look for maintenance or outages
Enable debug logging - Get detailed request/response information
Contact support - Reach out to internal@artosai.com with error details

Getting Started

API Reference

Core Concepts

Cookbooks

SDK Reference

Integrations

Deployment

Error Handling

Error Handling

HTTP Status Codes

Error Response Format

Common Errors

401 Unauthorized - Missing Token

401 Unauthorized - Invalid Token

403 Forbidden - Wrong Organization

404 Not Found - Resource Missing

400 Bad Request - Validation Error

422 Unprocessable Entity - Invalid Structure

500 Internal Server Error

Error Handling Best Practices

1. Implement Exponential Backoff

2. Check Status Codes

3. Handle Async Operations

4. Validate Input

5. Log Errors for Debugging

Debugging Tips

1. Enable Debug Logging

2. Check Token Validity

3. Test with curl

4. Review OpenAPI Spec

Support

Getting Started

API Reference

Core Concepts

Cookbooks

SDK Reference

Integrations

Deployment

Documentation Index

​Error Handling

​HTTP Status Codes

​Error Response Format

​Common Errors

​401 Unauthorized - Missing Token

​401 Unauthorized - Invalid Token

​403 Forbidden - Wrong Organization

​404 Not Found - Resource Missing

​400 Bad Request - Validation Error

​422 Unprocessable Entity - Invalid Structure

​500 Internal Server Error

​Error Handling Best Practices

​1. Implement Exponential Backoff

​2. Check Status Codes

​3. Handle Async Operations

​4. Validate Input

​5. Log Errors for Debugging

​Debugging Tips

​1. Enable Debug Logging

​2. Check Token Validity

​3. Test with curl

​4. Review OpenAPI Spec

​Support

Error Handling

HTTP Status Codes

Error Response Format

Common Errors

401 Unauthorized - Missing Token

401 Unauthorized - Invalid Token

403 Forbidden - Wrong Organization

404 Not Found - Resource Missing

400 Bad Request - Validation Error

422 Unprocessable Entity - Invalid Structure

500 Internal Server Error

Error Handling Best Practices

1. Implement Exponential Backoff

2. Check Status Codes

3. Handle Async Operations

4. Validate Input

5. Log Errors for Debugging

Debugging Tips

1. Enable Debug Logging

2. Check Token Validity

3. Test with curl

4. Review OpenAPI Spec

Support