Handle API errors gracefully in your integration.

HTTP Status Codes

• 200 OK: Request succeeded
• 201 Created: Resource created successfully
• 400 Bad Request: Invalid request parameters
• 401 Unauthorized: Invalid or missing API key
• 403 Forbidden: Insufficient permissions
• 404 Not Found: Resource doesn't exist
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server error
• 503 Service Unavailable: Temporary outage

Error Response Format

{
  "error": {
    "type": "validation_error",
    "message": "Invalid email address",
    "code": "invalid_email",
    "param": "customer.email",
    "doc_url": "https://docs.syncbooksapp.com/errors/invalid_email"
  }
}

Error Types

• api_error: Generic API error
• authentication_error: Invalid credentials
• validation_error: Invalid parameters
• rate_limit_error: Too many requests
• resource_not_found: Resource doesn't exist
• permission_error: Insufficient permissions

Handling Errors

try {
  const response = await syncbooks.invoices.create({
    customer: 'cus_123',
    amount: 1500.00
  });
} catch (error) {
  if (error.type === 'validation_error') {
    console.log('Invalid data:', error.message);
  } else if (error.type === 'rate_limit_error') {
    // Wait and retry
    await sleep(error.retryAfter * 1000);
  } else {
    // Log and alert
    console.error('API Error:', error);
  }
}

Best Practices

• Always check HTTP status codes
• Parse error responses for details
• Implement retry logic for 5xx errors
• Log errors for debugging
• Show user-friendly error messages
• Monitor error rates

Idempotency

Use idempotency keys to safely retry requests:

POST /api/v1/invoices
Idempotency-Key: unique-key-123

// Same key = same result, no duplicate invoice