Error Handling

Understand error responses and build resilient integrations.

Error Structure

All errors from SkillzDrive include these fields:

Error Response

{
  "error": "skill_not_found",
  "message": "No skill found with slug 'pdff'",
  "suggestions": ["Did you mean 'pdf-manipulation'?", "Try searching with skills_searchSkills"],
  "_workflow": {
    "failed": "Skill lookup",
    "nextSteps": [
      { "tool": "skills_searchSkills", "example": { "query": "pdf" } }
    ]
  }
}

Field	Type	Description
error	string	Machine-readable error code
message	string	Human-readable description — show this to users
suggestions	string[]	Recovery steps — show the first one as an action
_workflow	object	What failed and what tool to call next

"Did You Mean?" Suggestions

The server uses fuzzy matching (Levenshtein distance) to suggest corrections:

Misspelled skill slug → suggests closest match
Wrong script name → lists available scripts + closest match
Bad section slug → suggests similar sections

Auto-correction UX

Show "Did you mean X?" corrections as clickable options in your UI. Users appreciate auto-correction.

Common Errors

Error Code	Cause	Recovery
skill_not_found	Bad slug or no access	Check spelling, use `searchSkills`
script_not_found	Wrong script name	Call `listScripts` first, use exact name
section_not_found	Bad section slug	Call `docTOC` first
access_denied	Key doesn't have access	Check `allowed_skill_ids` on your key
session_not_found	Session expired	Re-run script with `reuseSession: true`
quota_exceeded	Monthly execution limit	Upgrade plan or wait for reset
missing_credentials	User hasn't set up required API key	Direct user to Account settings

Script Execution Errors

When a script fails (exitCode !== 0), the error is different from API errors:

The error field contains stderr directly (up to 100 lines)
No separate readFile call needed
Still check suggestions for recovery steps

Script Failure

{
  "success": false,
  "exitCode": 1,
  "error": "FileNotFoundError: No such file: input.pdf",
  "executionTimeMs": 234,
  "suggestions": ["Check that the input file path is correct"]
}

UI Error Display Patterns

Scenario	What to Show	Example
API error	Error message + first suggestion	"No skill found. Did you mean 'pdf-manipulation'?"
Script failure	Stderr summary + recovery	"Script failed: file not found. Check input path."
Session expired	Auto-retry message	"Session expired. Re-running script..."
Auth failure	Link to settings	"API key invalid. Update in Account settings."
Rate limited	Wait message	"Rate limit reached. Retrying in 30 seconds..."

User-facing errors

Never show raw JSON-RPC errors or full stack traces to users. Extract the message and suggestions fields and present them cleanly.

Building Resilient Integrations

Best practices for handling errors gracefully:

1Always follow _workflow.nextSteps — the server tells you how to recover
2Handle session expiry gracefully — re-run the script if the session is gone
3Cache aggressively — fewer calls = fewer chances for errors
4Show suggestions as actions — turn "Did you mean X?" into clickable buttons
5Log errors for debugging — store the full error object, show users only the message