Error Codes Reference

Complete reference of all error codes returned by the Lorn AI API.

HTTP Status Codes

Code	Name	Description
`200`	OK	Request succeeded
`201`	Created	Resource created successfully
`400`	Bad Request	Invalid request parameters
`401`	Unauthorized	Invalid or missing API key
`403`	Forbidden	API key lacks required permissions
`404`	Not Found	Resource does not exist
`405`	Method Not Allowed	Invalid operation for current state
`409`	Conflict	Idempotency key conflict
`422`	Unprocessable Entity	Valid syntax but semantic errors
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Unexpected server error
`502`	Bad Gateway	Upstream service error
`503`	Service Unavailable	Service temporarily unavailable

Error Response Format

Standard Error

{
  "detail": "Error message describing what went wrong"
}

Structured Error

{
  "error": {
    "type": "invalid_request",
    "code": "missing_required_field",
    "message": "The 'items' field is required",
    "param": "items"
  }
}

Checkout Error with Messages

{
  "checkout_session": {
    "id": "cs_demo_abc123",
    "status": "not_ready_for_payment",
    "messages": [
      {
        "type": "error",
        "code": "out_of_stock",
        "path": "$.line_items[0]",
        "content_type": "plain",
        "content": "This item is no longer available."
      }
    ]
  }
}

Error Types

invalid_request

Client sent an invalid request.

Code	Description	Solution
`missing_required_field`	Required field not provided	Add the missing field
`invalid_format`	Field has wrong format	Check field format requirements
`invalid_value`	Field value is invalid	Use valid value
`request_not_idempotent`	Same idempotency key, different params	Use new idempotency key

authentication_error

Authentication failed.

Code	Description	Solution
`invalid_api_key`	API key is invalid	Check API key is correct
`expired_api_key`	API key has expired	Request new API key
`missing_api_key`	No API key provided	Add X-ACP-API-Key header

authorization_error

Authorization failed.

Code	Description	Solution
`insufficient_permissions`	Key lacks required permissions	Request elevated permissions
`resource_not_accessible`	Cannot access this resource	Check resource ownership

not_found

Resource not found.

Code	Description	Solution
`product_not_found`	Product ID doesn’t exist	Verify product ID
`session_not_found`	Checkout session doesn’t exist	Create new session
`variant_not_found`	Variant SKU doesn’t exist	Verify variant SKU

rate_limit_exceeded

Too many requests.

Code	Description	Solution
`rate_limit_exceeded`	Exceeded request rate limit	Wait and retry

processing_error

Server-side processing error.

Code	Description	Solution
`internal_error`	Unexpected server error	Retry request
`database_error`	Database operation failed	Retry request

service_unavailable

Service temporarily unavailable.

Code	Description	Solution
`backend_not_configured`	Backend services not set up	Contact support
`maintenance`	Service under maintenance	Wait and retry

Checkout-Specific Errors

Product Errors

Code	Path	Description
`out_of_stock`	`$.line_items[n]`	Product is out of stock
`insufficient_inventory`	`$.line_items[n]`	Not enough stock for quantity
`product_unavailable`	`$.line_items[n]`	Product no longer available
`invalid_variant`	`$.line_items[n]`	Variant doesn’t exist

Address Errors

Code	Path	Description
`invalid_address`	`$.shipping_address`	Address validation failed
`unsupported_region`	`$.shipping_address`	Cannot ship to this region
`missing_address`	`$.shipping_address`	Shipping address required

Payment Errors

Code	Path	Description
`payment_declined`	`$.payment_method`	Payment was declined
`invalid_payment_method`	`$.payment_method`	Payment method invalid
`requires_3ds`	`$.payment_method`	3D Secure required

State Errors

Code	Description
`session_completed`	Cannot modify completed session
`session_canceled`	Cannot modify canceled session
`cannot_cancel`	Session cannot be canceled

Handling Errors by Language

Python

import requests
 
try:
    response = requests.get(f"{BASE_URL}/acp/products/invalid_id", headers=HEADERS)
    response.raise_for_status()
except requests.exceptions.HTTPError as e:
    status = e.response.status_code
    body = e.response.json()
    
    if status == 400:
        print(f"Bad request: {body.get('detail')}")
    elif status == 401:
        print("Invalid API key")
    elif status == 404:
        print("Resource not found")
    elif status == 429:
        retry_after = e.response.headers.get('Retry-After', 60)
        print(f"Rate limited. Retry after {retry_after}s")
    elif status >= 500:
        print("Server error. Please retry.")
    else:
        print(f"Error {status}: {body}")

TypeScript

try {
  const response = await fetch(`${BASE_URL}/acp/products/invalid_id`, {
    headers: { "X-ACP-API-Key": API_KEY }
  });
  
  if (!response.ok) {
    const body = await response.json();
    
    switch (response.status) {
      case 400:
        console.error(`Bad request: ${body.detail}`);
        break;
      case 401:
        console.error("Invalid API key");
        break;
      case 404:
        console.error("Resource not found");
        break;
      case 429:
        const retryAfter = response.headers.get("Retry-After") || "60";
        console.error(`Rate limited. Retry after ${retryAfter}s`);
        break;
      default:
        console.error(`Error ${response.status}: ${JSON.stringify(body)}`);
    }
  }
} catch (error) {
  console.error("Network error:", error);
}

Java

try {
    String result = client.getProduct("invalid_id");
} catch (RuntimeException e) {
    String message = e.getMessage();
    
    if (message.contains("400")) {
        System.err.println("Bad request");
    } else if (message.contains("401")) {
        System.err.println("Invalid API key");
    } else if (message.contains("404")) {
        System.err.println("Resource not found");
    } else if (message.contains("429")) {
        System.err.println("Rate limited");
    } else if (message.contains("500") || message.contains("503")) {
        System.err.println("Server error - retry later");
    }
}

Go

_, err := client.GetProduct("invalid_id")
if err != nil {
    errStr := err.Error()
    
    switch {
    case strings.Contains(errStr, "400"):
        log.Println("Bad request")
    case strings.Contains(errStr, "401"):
        log.Println("Invalid API key")
    case strings.Contains(errStr, "404"):
        log.Println("Resource not found")
    case strings.Contains(errStr, "429"):
        log.Println("Rate limited")
    case strings.Contains(errStr, "500"), strings.Contains(errStr, "503"):
        log.Println("Server error - retry later")
    default:
        log.Printf("Error: %s\n", errStr)
    }
}

Retry Strategy

Retryable Errors

Status	Retryable	Strategy
408	Yes	Immediate retry
429	Yes	Wait for Retry-After header
500	Yes	Exponential backoff
502	Yes	Exponential backoff
503	Yes	Wait for Retry-After or exponential backoff
504	Yes	Exponential backoff

Non-Retryable Errors

Status	Retryable	Action
400	No	Fix request
401	No	Fix authentication
403	No	Check permissions
404	No	Resource doesn’t exist
405	No	Invalid operation
409	No	Handle conflict
422	No	Fix request data

Exponential Backoff

import time
import random
 
def retry_with_backoff(func, max_retries=3, base_delay=1):
    for attempt in range(max_retries):
        try:
            return func()
        except RetryableError as e:
            if attempt == max_retries - 1:
                raise
            
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            time.sleep(delay)

Common Issues

”Supabase not configured”

{
  "detail": "Supabase not configured. Set SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, and OPENAI_API_KEY."
}

Cause: Backend environment variables not set.

Solution: Contact support to verify backend configuration.

”Unknown product_id”

{
  "detail": "Unknown product_id prod_xyz"
}

Cause: Product ID doesn’t exist in catalog.

Solution:

Verify the product ID from search results
Ensure the product is still available
Check for typos in product ID

”Checkout session not found”

{
  "detail": "Checkout session not found"
}

Cause: Session ID is invalid or expired.

Solution:

Verify the session ID
Create a new checkout session
Sessions may expire after inactivity

”Cannot cancel session with status ‘completed’”

{
  "detail": "Cannot cancel session with status 'completed'"
}

Cause: Trying to cancel an already completed order.

Solution: Completed orders cannot be canceled via API. Use refund process instead.

Getting Help

If you encounter errors not covered here:

Check the error message — Often contains specific guidance
Review request format — Ensure JSON is valid and fields match spec
Verify API version — Some errors may be version-specific
Contact support — Include request ID and timestamp

Support email: mayank@lornai.com.com

Object Reference Changelog