​

Troubleshooting

​

Repair Failed

​

Input Not Valid JSON

{
  "success": false,
  "metadata": {
    "errors": [{
      "code": "UNRECOVERABLE_SYNTAX_ERROR",
      "message": "The JSON structure is too malformed to repair"
    }]
  }
}

• LLM output is not JSON at all
• Input is completely malformed

1. Check LLM prompt includes “output JSON”
2. Use JSON mode if available (OpenAI, Anthropic)
3. Add example JSON in prompt

​

Schema Validation Failed

{
  "success": false,
  "metadata": {
    "errors": [{
      "code": "SCHEMA_VALIDATION_FAILED",
      "field": "age"
    }]
  }
}

• Repaired JSON doesn’t match schema
• Required field missing
• Type coercion failed

1. Review metadata.errors for specific field
2. Check schema matches expected LLM output
3. Use lenient mode during development
4. Add field to schema or make it optional

​

Low Confidence

{
  "success": true,
  "metadata": {
    "confidence": "low"
  }
}

• Ambiguous repairs
• Multiple possible fixes
• Risky type coercion

1. Review metadata.repairs_applied
2. Check metadata.warnings
3. Improve LLM prompt for clearer output
4. Add schema for type guidance

​

Rate Limit Exceeded

{
  "success": false,
  "metadata": {
    "errors": [{
      "code": "RATE_LIMIT_EXCEEDED",
      "message": "Rate limit exceeded for Free tier"
    }]
  }
}

1. Upgrade to Pro or Team tier
2. Wait until next month (limits reset monthly)
3. Cache repaired results to reduce requests

​

Session Not Found

{
  "error": {
    "code": "SESSION_NOT_FOUND",
    "message": "Session not found or expired"
  }
}

• Session expired (60s TTL)
• Invalid session ID
• Session already finalized

1. Create new session with /v1/repair/stream/start
2. Reduce time between chunks
3. Don’t reuse session IDs

​

Buffer Size Exceeded

{
  "error": {
    "code": "BUFFER_SIZE_EXCEEDED",
    "message": "Buffer size exceeded 5MB limit"
  }
}

• LLM hallucination loop
• Extremely large output
• Attack attempt

1. Add max_tokens limit to LLM
2. Monitor LLM output length
3. Use batch repair for large outputs

​

Payload Too Large

{
  "success": false,
  "metadata": {
    "errors": [{
      "code": "PAYLOAD_TOO_LARGE",
      "message": "Input size exceeds 5MB limit"
    }]
  }
}

1. Use streaming repair for large outputs
2. Split input into smaller chunks
3. Reduce LLM max_tokens

​

Invalid API Key

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key is invalid"
  }
}

1. Check API key format: sk_live_xxxxx
2. Verify key in console
3. Generate new key if revoked
4. Check Authorization header format: Bearer sk_live_xxxxx

​

Slow Response Times

• Large input size
• Complex schema validation
• Network latency

1. Use streaming repair for real-time processing
2. Simplify schema (remove unnecessary fields)
3. Use CDN or edge deployment
4. Check network latency to api.shim.so

​

Type Coercion Not Working

• No schema provided
• Field not in schema properties

1. Add schema with correct types
2. Include field in schema properties

​

Extra Fields Removed

• Strict mode enabled (default)
• Field not in schema

1. Use lenient mode: { mode: 'lenient' }
2. Add field to schema
3. Check metadata.warnings for removed fields

​

Getting Help

1. Check error code: See Error Codes
2. Review metadata: Look at repairs_applied, warnings, errors
3. Test with cURL: Isolate SDK vs API issues
4. Contact support: Include X-Request-ID header value

​

Debug Checklist

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

// 1. Check success
console.log('Success:', result.success);

// 2. Check confidence
console.log('Confidence:', result.metadata.confidence);

// 3. Review repairs
console.log('Repairs:', result.metadata.repairs_applied);

// 4. Check warnings
console.log('Warnings:', result.metadata.warnings);

// 5. Check errors
console.log('Errors:', result.metadata.errors);

// 6. Verify output
console.log('Valid JSON:', result.metadata.output_valid_json);

​

Next Steps