openrouter-common-errors skill

Overview

This skill diagnoses and fixes common OpenRouter API errors to restore reliable requests and responses. It guides you through verifying credentials, interpreting HTTP status codes, and adjusting rate limits and request payloads. The goal is quick remediation and practical fixes you can apply in development or production.

How this skill works

The skill inspects request and response logs to identify frequent failure patterns such as authentication issues (401), rate limits (429), malformed payloads (400), and server errors (5xx). It maps each error to concrete checks and remediation steps: credential validation, header and endpoint verification, retry/backoff adjustments, and payload validation. It also suggests monitoring and logging changes to prevent recurrence.

When to use it

• When OpenRouter API requests fail with 401, 403, 400, 429, or 5xx status codes
• When authentication tokens or keys are not accepted
• When you observe frequent rate-limit responses or throttling
• During integration testing after configuration changes
• When debugging unexpected model responses or malformed payload errors

Best practices

• Confirm API key, secret, and environment variables match the active OpenRouter account
• Log full request and response headers and bodies (redact secrets) to pinpoint causes
• Implement exponential backoff and jitter for rate-limit (429) handling
• Validate JSON payloads and required fields before sending requests
• Monitor OpenRouter status and set alerts for spikes in 429/5xx errors
• Use short verification scripts to isolate network, DNS, or proxy issues before changing production code

Example use cases

• Fix 401 Unauthorized by rotating API keys and checking environment variable names
• Resolve 429 Too Many Requests by adding retry logic with exponential backoff and reducing request rate
• Correct 400 Bad Request by validating model parameters and trimming oversized inputs
• Diagnose 5xx errors by checking service status, retrying with backoff, and routing logs to observability tools
• Verify connectivity by sending a simple health-check request and comparing response headers

FAQ