> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shim.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes

> Complete error reference

# 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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

<CardGroup cols={2}>
  <Card title="Batch Endpoint" icon="code" href="/reference/batch-endpoint">
    API reference for batch repair
  </Card>

  <Card title="Streaming Endpoints" icon="stream" href="/reference/streaming-endpoints">
    API reference for streaming repair
  </Card>

  <Card title="Error Handling Guide" icon="book" href="/guides/handling-errors">
    Best practices for error handling
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/guides/rate-limits">
    Understand tier limits
  </Card>
</CardGroup>