Error Codes

All errors return HTTP 200 with structured envelope. Check success field and metadata.errors array.

Request Errors

INVALID_REQUEST

Cause: Missing or invalid parameters Example:

{
  "code": "INVALID_REQUEST",
  "message": "Request validation failed",
  "severity": "critical",
  "recoverable": false,
  "suggestion": "raw_output is required"
}

Fix: Check request body matches API spec

PAYLOAD_TOO_LARGE

Cause: Input exceeds size limit Limits:

Batch repair: 5MB
Streaming chunk: 5MB per chunk

Example:

{
  "code": "PAYLOAD_TOO_LARGE",
  "message": "Input size exceeds 5MB limit",
  "severity": "critical",
  "recoverable": false,
  "suggestion": "Reduce input size or use streaming endpoint"
}

Fix: Split large inputs into smaller chunks using streaming

Repair Errors

UNRECOVERABLE_SYNTAX_ERROR

Cause: Input contains no recoverable JSON structure after syntax repair Example:

{
  "code": "UNRECOVERABLE_SYNTAX_ERROR",
  "message": "Failed to parse JSON",
  "severity": "critical",
  "recoverable": false,
  "suggestion": "The JSON structure is too malformed to repair. Check LLM output."
}

Fix: Verify LLM is configured for JSON output

SCHEMA_VALIDATION_FAILED

Cause: Repaired JSON doesn’t match provided schema Example:

{
  "code": "SCHEMA_VALIDATION_FAILED",
  "message": "Repaired output does not match schema",
  "field": "age",
  "severity": "high",
  "recoverable": false,
  "suggestion": "Check schema definition or LLM prompt"
}

Fix: Review schema or adjust LLM prompt

Session Errors

SESSION_NOT_FOUND

Cause: Streaming session expired or doesn’t exist Session TTL: 60 seconds Example:

{
  "code": "SESSION_NOT_FOUND",
  "message": "Session not found or expired",
  "severity": "critical",
  "recoverable": true,
  "suggestion": "Create a new session with POST /v1/repair/stream/start"
}

Fix: Create new session or reduce time between chunks

BUFFER_SIZE_EXCEEDED

Cause: Session buffer exceeded limit (possible hallucination loop) Circuit Breaker: 5MB buffer limit Example:

{
  "code": "BUFFER_SIZE_EXCEEDED",
  "message": "Buffer size exceeded 5MB limit",
  "severity": "critical",
  "recoverable": false,
  "suggestion": "Possible hallucination loop or attack. Session terminated."
}

Fix: Check LLM for hallucination loops, add max tokens limit

Service Errors

SERVICE_UNAVAILABLE

Cause: Server at maximum capacity Example:

{
  "code": "SERVICE_UNAVAILABLE",
  "message": "Server is at maximum capacity. Please try again later.",
  "severity": "critical",
  "recoverable": true,
  "suggestion": "Retry with exponential backoff"
}

Fix: Retry with exponential backoff

INTERNAL_ERROR

Cause: Unexpected server error Example:

{
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred",
  "severity": "critical",
  "recoverable": false,
  "suggestion": "Contact support with request ID: req_abc123"
}

Fix: Contact support with request ID from X-Request-ID header

Authentication Errors

INVALID_API_KEY

Cause: API key is invalid or revoked Example:

{
  "code": "INVALID_API_KEY",
  "message": "API key is invalid",
  "severity": "critical",
  "recoverable": false,
  "suggestion": "Check API key in console"
}

Fix: Generate new API key in console

RATE_LIMIT_EXCEEDED

Cause: Exceeded tier rate limit Example:

{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded for Free tier",
  "severity": "high",
  "recoverable": true,
  "suggestion": "Upgrade to Pro tier or wait until next month"
}

Fix: Upgrade tier or wait for limit reset

Error Response Structure

All errors follow this structure:

interface RepairError {
  code: string;           // Error code (see above)
  message: string;        // Human-readable message
  field?: string;         // Field that caused error (if applicable)
  severity: 'critical' | 'high' | 'medium';
  recoverable: boolean;   // Can you retry?
  suggestion?: string;    // How to fix
}

Handling Errors

Check Success Field

const result = await shim.repair({ raw_output: input });

if (!result.success) {
  console.error('Repair failed:', result.metadata.errors);
  
  // Check if recoverable
  const canRetry = result.metadata.errors.every(e => e.recoverable);
  
  if (canRetry) {
    // Retry logic
  } else {
    // Log and alert
  }
}

Retry Logic

async function repairWithRetry(input: string, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const result = await shim.repair({ raw_output: input });
    
    if (result.success) {
      return result.repaired;
    }
    
    // Check if recoverable
    const canRetry = result.metadata.errors.every(e => e.recoverable);
    if (!canRetry) {
      throw new Error('Unrecoverable error');
    }
    
    // Exponential backoff
    await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
  }
  
  throw new Error('Max retries exceeded');
}

Next Steps

Batch Endpoint

API reference for batch repair

Streaming Endpoints

API reference for streaming repair

Error Handling Guide

Best practices for error handling

Rate Limits

Understand tier limits

Getting Started

Guides

Concepts

API Reference

SDKs

Migration

Error Codes

Error Codes

Request Errors

INVALID_REQUEST

PAYLOAD_TOO_LARGE

Repair Errors

UNRECOVERABLE_SYNTAX_ERROR

SCHEMA_VALIDATION_FAILED

Session Errors

SESSION_NOT_FOUND

BUFFER_SIZE_EXCEEDED

Service Errors

SERVICE_UNAVAILABLE

INTERNAL_ERROR

Authentication Errors

INVALID_API_KEY

RATE_LIMIT_EXCEEDED

Error Response Structure

Handling Errors

Check Success Field

Retry Logic

Next Steps

Batch Endpoint

Streaming Endpoints

Error Handling Guide

Rate Limits

​Error Codes

​Request Errors

​INVALID_REQUEST

​PAYLOAD_TOO_LARGE

​Repair Errors

​UNRECOVERABLE_SYNTAX_ERROR

​SCHEMA_VALIDATION_FAILED

​Session Errors

​SESSION_NOT_FOUND

​BUFFER_SIZE_EXCEEDED

​Service Errors

​SERVICE_UNAVAILABLE

​INTERNAL_ERROR

​Authentication Errors

​INVALID_API_KEY

​RATE_LIMIT_EXCEEDED

​Error Response Structure

​Handling Errors

​Check Success Field

​Retry Logic

​Next Steps

Batch Endpoint

Streaming Endpoints

Error Handling Guide

Rate Limits

Error Codes

Request Errors

INVALID_REQUEST

PAYLOAD_TOO_LARGE

Repair Errors

UNRECOVERABLE_SYNTAX_ERROR

SCHEMA_VALIDATION_FAILED

Session Errors

SESSION_NOT_FOUND

BUFFER_SIZE_EXCEEDED

Service Errors

SERVICE_UNAVAILABLE

INTERNAL_ERROR

Authentication Errors

INVALID_API_KEY

RATE_LIMIT_EXCEEDED

Error Response Structure

Handling Errors

Check Success Field

Retry Logic

Next Steps