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

​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