Error Codes

All error responses follow this format:

{

  "ok": false,


  "error": "Human-readable error message",


  "hint": "Optional suggestion for fixing the issue"


}

HTTP Status Codes

400 — Bad Request

Cause: Malformed request, missing required fields, or invalid parameters. Examples:
  • Missing request body on POST endpoints
  • Invalid JSON in request body
  • Missing required query parameters
Fix: Check the API reference for required fields.

401 — Unauthorized

Cause: Missing or invalid authentication. Examples:
  • No Authorization or X-API-Key header
  • Invalid API key format (must start with pincer_sk_)
  • Key not found in database
Fix: Ensure you're sending a valid API key: 
-H "Authorization: Bearer pincer_sk_YOUR_KEY"

402 — Payment Required

Cause: Valid authentication but insufficient balance. Response includes: 
{

  "ok": false,


  "error": "Insufficient balance",


  "balance": 0.003,


  "cost": 0.01,


  "hint": "Add funds via POST /api/v1/balance or use x402 payment"


}

Fix: Add funds via the dashboard or set up auto-reload.

403 — Forbidden

Cause: API key is disabled or revoked, or you don't have permission. Fix: Check key status in Dashboard → API Keys. Create a new key if needed.

404 — Not Found

Cause: The requested resource doesn't exist. Examples:
  • API ID not in the directory
  • Cookbook not found
  • Session ID doesn't exist
  • Doc page not found
Fix: Check the ID/slug. Use GET /api/v1/apis to list available APIs.

429 — Rate Limited

Cause: Too many requests in a short period. Response headers:
  • Retry-After: Seconds to wait before retrying
  • X-RateLimit-Limit: Max requests per window
  • X-RateLimit-Remaining: Remaining requests
Fix: Implement exponential backoff. Respect the Retry-After header.

502 — Bad Gateway

Cause: The downstream API returned an error during proxying. Fix: Check the downstream API's status. The response body contains the downstream error.

503 — Service Unavailable

Cause: The downstream API is temporarily unavailable. Fix: Retry after a short delay. Check the API's status page.

Debugging Tips

  • Check response headers — X-Pincer-Cost and X-Pincer-Balance tell you billing state
  • Use GET /api/v1/health — Verify PincerAPI is up
  • Check GET /api/v1/balance — Verify you have funds
  • Test with curl first — Isolate whether the issue is your code or the API
  • Check the API directory — Verify the API ID exists and is active