8 min read

Error Handling

Learn how to handle API errors gracefully and implement retry logic.

Error Response Format

All error responses from the Pipe Solar API follow a consistent format:

{
  "error": {
    "code": "invalid_request",
    "message": "The 'capacity_kw' field must be a positive number.",
    "param": "capacity_kw",
    "status": 422
  }
}

HTTP Status Codes

Code	Meaning	Action
`400`	Bad Request	Check request body/params
`401`	Unauthorized	Check API key
`404`	Not Found	Verify resource ID
`422`	Validation Error	Fix input data
`429`	Rate Limited	Wait and retry with backoff
`500`	Server Error	Retry; contact support if persists

Retry Strategy

For 429 and 5xx errors, implement exponential backoff:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.ok) return response.json();

    if (response.status === 429 || response.status >= 500) {
      const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
      await new Promise(r => setTimeout(r, delay));
      continue;
    }

    // Non-retryable error
    throw new Error(`API error: ${response.status}`);
  }
  throw new Error("Max retries exceeded");
}