{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": [
      {
        "field": "fieldName",
        "message": "Specific field error"
      }
    ],
    "hint": "Suggestion for resolution"
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "hint": "Include an API key or JWT token in your request"
  }
}

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked",
    "hint": "Verify your API key in the dashboard settings"
  }
}

{
  "error": {
    "code": "TOKEN_EXPIRED",
    "message": "Access token has expired",
    "hint": "Use your refresh token to obtain a new access token"
  }
}

{
  "error": {
    "code": "INVALID_TOKEN",
    "message": "The provided token is invalid",
    "hint": "Ensure the token is properly formatted and not corrupted"
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to access this resource",
    "hint": "Contact your organization administrator to request access"
  }
}

{
  "error": {
    "code": "SCOPE_INSUFFICIENT",
    "message": "API key does not have the required scope",
    "details": [
      {
        "required": "traces:write",
        "provided": ["prompts:read"]
      }
    ]
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "name",
        "message": "Name is required"
      },
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  }
}

{
  "error": {
    "code": "INVALID_JSON",
    "message": "Request body contains invalid JSON",
    "hint": "Check for syntax errors in your JSON payload"
  }
}

{
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "Required field is missing",
    "details": [
      {
        "field": "projectId",
        "message": "projectId is required"
      }
    ]
  }
}

{
  "error": {
    "code": "INVALID_FIELD_TYPE",
    "message": "Field has invalid type",
    "details": [
      {
        "field": "pageSize",
        "expected": "integer",
        "received": "string"
      }
    ]
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "details": [
      {
        "resource": "Trace",
        "id": "trace_nonexistent"
      }
    ]
  }
}

{
  "error": {
    "code": "RESOURCE_EXISTS",
    "message": "Resource already exists",
    "details": [
      {
        "resource": "ApiKey",
        "field": "name",
        "value": "Production Key"
      }
    ]
  }
}

{
  "error": {
    "code": "CONFLICT",
    "message": "Resource was modified by another request",
    "hint": "Fetch the latest version and retry your update"
  }
}

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "retryAfter": 60,
    "hint": "Wait 60 seconds before retrying"
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred",
    "hint": "Please try again. If the problem persists, contact support."
  }
}

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable",
    "retryAfter": 30,
    "hint": "The service is under maintenance. Please try again soon."
  }
}

{
  "error": {
    "code": "DEPENDENCY_ERROR",
    "message": "External service temporarily unavailable",
    "hint": "A third-party service is experiencing issues. Please retry."
  }
}

from brokle import Brokle
from brokle.exceptions import (
    BrokleError,
    AuthenticationError,
    ValidationError,
    RateLimitError,
    NotFoundError
)

client = Brokle(api_key="bk_...")

try:
    result = await client.traces.get("trace_123")
except AuthenticationError as e:
    print(f"Auth failed: {e.message}")
    # Re-authenticate or check API key
except ValidationError as e:
    print(f"Validation failed: {e.message}")
    for detail in e.details:
        print(f"  {detail['field']}: {detail['message']}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
    time.sleep(e.retry_after)
    # Retry request
except NotFoundError as e:
    print(f"Resource not found: {e.message}")
except BrokleError as e:
    print(f"Brokle error: {e.message} (code: {e.code})")

import { Brokle } from 'brokle';
import {
  BrokleError,
  AuthenticationError,
  ValidationError,
  RateLimitError,
  NotFoundError
} from 'brokle/errors';

const client = new Brokle({ apiKey: 'bk_...' });

try {
  const result = await client.traces.get('trace_123');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Auth failed:', error.message);
    // Re-authenticate or check API key
  } else if (error instanceof ValidationError) {
    console.error('Validation failed:', error.message);
    error.details?.forEach(detail => {
      console.error(`  ${detail.field}: ${detail.message}`);
    });
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter} seconds`);
    await new Promise(r => setTimeout(r, error.retryAfter * 1000));
    // Retry request
  } else if (error instanceof NotFoundError) {
    console.error('Resource not found:', error.message);
  } else if (error instanceof BrokleError) {
    console.error(`Brokle error: ${error.message} (code: ${error.code})`);
  }
}

import time
import random

def retry_with_backoff(func, max_retries=5, base_delay=1):
    for attempt in range(max_retries):
        try:
            return func()
        except (RateLimitError, InternalError) as e:
            if attempt == max_retries - 1:
                raise

            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            time.sleep(delay)