Error Handling

{
  "error": "Brief, human-readable error description",
  "detail": "Detailed explanation of what went wrong",
  "error_code": "MACHINE_READABLE_ERROR_CODE",
  "retryable": false,
  "request_id": "a1b2c3d4e5f67890abcdef1234567890"
}

{
  "error": "Authentication failed",
  "detail": "Invalid or missing authentication credentials.",
  "error_code": "AUTH_FAILED",
  "retryable": false,
  "request_id": "a1b2c3d4e5f67890abcdef1234567890"
}

{
  "error": "The request carries no API key.",
  "detail": "No API key was provided. Send it as 'Authorization: Bearer <your-api-key>'. Get a key at https://app.anyformat.ai/api-key.",
  "error_code": "MISSING_API_KEY",
  "retryable": false,
  "request_id": "a1b2c3d4e5f67890abcdef1234567890"
}

{
  "error": "You do not have access to this resource.",
  "detail": "You do not have permission to perform this action.",
  "error_code": "ACCESS_DENIED",
  "retryable": false,
  "request_id": "a1b2c3d4e5f67890abcdef1234567890"
}

{
  "error": "Validation failed",
  "detail": [
    {"type": "missing", "loc": ["body", "name"], "msg": "Field required"},
    {"type": "missing", "loc": ["body", "fields"], "msg": "Field required"}
  ],
  "error_code": "VALIDATION_ERROR",
  "retryable": false,
  "request_id": "a1b2c3d4e5f67890abcdef1234567890"
}

{
  "error": "Invalid JSON format",
  "detail": "The request body contains invalid JSON. Please check your JSON syntax.",
  "error_code": "INVALID_JSON",
  "retryable": false,
  "request_id": "a1b2c3d4e5f67890abcdef1234567890"
}

{
  "error": "Resource not found",
  "detail": "The requested resource could not be found.",
  "error_code": "NOT_FOUND",
  "retryable": false,
  "request_id": "a1b2c3d4e5f67890abcdef1234567890"
}

{
  "error": "Rate limited",
  "detail": "Rate limit exceeded. Try again in 12s.",
  "error_code": "RATE_LIMITED",
  "retryable": true,
  "request_id": "a1b2c3d4e5f67890abcdef1234567890"
}

{
  "error": "Internal server error",
  "detail": "An unexpected error occurred while processing your request. Please try again or contact support.",
  "error_code": "INTERNAL_ERROR",
  "retryable": true,
  "request_id": "a1b2c3d4e5f67890abcdef1234567890"
}

{
  "error": "Gateway timeout",
  "detail": "The backend did not respond in time. Please try again.",
  "error_code": "GATEWAY_TIMEOUT",
  "retryable": true,
  "request_id": "a1b2c3d4e5f67890abcdef1234567890"
}

import requests

response = requests.get(
    "https://api.anyformat.ai/v3/workflows/",
    headers={"Authorization": "Bearer your-api-key"}
)

if response.status_code == 200:
    workflows = response.json()
elif response.status_code == 401:
    print("Authentication failed. Check that you send a valid API key.")
elif response.status_code == 403:
    print("Access denied. The API key has no access to this resource.")
elif response.status_code == 404:
    print("Resource not found.")
elif response.status_code == 429:
    retry_after = response.headers.get("Retry-After", "5")
    print(f"Rate limited. Retry after {retry_after}s.")
elif response.status_code >= 500:
    print("Server error. Retry with backoff.")
else:
    error = response.json()
    print(f"Error: {error.get('detail')}")

def handle_api_error(response):
    if response.status_code >= 400:
        error_data = response.json()
        error_code = error_data.get('error_code')

        if error_code in ('MISSING_API_KEY', 'INVALID_API_KEY', 'AUTH_FAILED'):
            print("Missing or invalid API key.")
        elif error_code == 'ACCESS_DENIED':
            print("The API key has no access to this resource.")
        elif error_code == 'VALIDATION_ERROR':
            show_validation_error(error_data.get('detail'))
        elif error_code == 'NOT_FOUND':
            handle_missing_resource()
        elif error_code == 'RATE_LIMITED':
            retry_after = int(response.headers.get('Retry-After', 5))
            time.sleep(retry_after)
            return retry_request()
        elif error_code == 'INTERNAL_ERROR':
            retry_with_backoff()
        elif error_code == 'GATEWAY_TIMEOUT':
            retry_with_backoff()
        else:
            log_unexpected_error(error_data)

import time
import random

def api_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries + 1):
        try:
            response = requests.get(url, headers=headers)

            # Don't retry non-retryable client errors
            if 400 <= response.status_code < 500 and response.status_code != 429:
                return response

            # Handle rate limiting
            if response.status_code == 429:
                delay = int(response.headers.get('Retry-After', 5))
                time.sleep(delay)
                continue

            # Retry server errors (5xx)
            if response.status_code >= 500 and attempt < max_retries:
                delay = (2 ** attempt) + random.uniform(0, 1)
                time.sleep(delay)
                continue

            return response

        except requests.exceptions.RequestException as e:
            if attempt < max_retries:
                delay = (2 ** attempt) + random.uniform(0, 1)
                time.sleep(delay)
                continue
            raise e

def create_workflow(name, description, nodes, edges):
    # Validate required fields locally first
    if not name:
        raise ValueError("Workflow name is required")
    if not nodes:
        raise ValueError("At least one node is required")

    node_ids = {node.get("id") for node in nodes}
    for edge in edges:
        if edge.get("source") not in node_ids or edge.get("target") not in node_ids:
            raise ValueError("Every edge must connect two declared nodes")

    # Make API request
    response = requests.post(
        "https://api.anyformat.ai/v3/workflows/",
        headers={"Authorization": "Bearer your-api-key", "Content-Type": "application/json"},
        json={"name": name, "description": description, "nodes": nodes, "edges": edges}
    )

    return handle_response(response)

import logging

def log_api_error(response, context=""):
    # Log codes and ids only: `detail` and the raw body can echo document content.
    try:
        error_data = response.json()
        error_code = error_data.get('error_code', 'UNKNOWN')
        request_id = error_data.get('request_id', 'N/A')
    except ValueError:
        error_code, request_id = 'NON_JSON_RESPONSE', 'N/A'

    logging.error(
        f"API Error {response.status_code}: {error_code} "
        f"[Context: {context}] [Request: {request_id}]"
    )