Error Handling

Understanding error responses and how to handle them in your application.

Error Response Format

All API errors follow a consistent structure:

Error responsejson

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Missing required field: policyType",
    "details": {
      "field": "policyType",
      "expected": "string"
    }
  }
}

Common Error Codes

400

Bad Request

Invalid request format or missing required fields.

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid policy type"
  }
}

401

Unauthorized

Missing or invalid API key, or signature verification failed.

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_FAILED",
    "message": "Invalid API key or signature"
  }
}

403

Forbidden

Your plan doesn't include this feature or you've exceeded your quota.

{
  "success": false,
  "error": {
    "code": "FEATURE_NOT_AVAILABLE",
    "message": "Webhooks require Starter plan or higher"
  }
}

429

Too Many Requests

Rate limit exceeded. Wait before making more requests.

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "retryAfter": 60
  }
}

500

Server Error

Something went wrong on our end. Please try again or contact support.

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  }
}

Handling Errors in Your Code

Error handling examplejavascript

const axios = require('axios');

try {
  const response = await axios.post(apiUrl, data, { headers });
  console.log('Success:', response.data);
} catch (error) {
  if (error.response) {
    const { status, data } = error.response;

    switch (status) {
      case 400:
        console.error('Validation error:', data.error.message);
        break;
      case 401:
        console.error('Authentication failed. Check API key');
        break;
      case 403:
        console.error('Upgrade plan:', data.error.message);
        break;
      case 429:
        console.error('Rate limited. Retry after:', data.error.retryAfter);
        setTimeout(() => retryRequest(), data.error.retryAfter * 1000);
        break;
      case 500:
        console.error('Server error. Contact support');
        break;
      default:
        console.error('Unexpected error:', status);
    }
  }
}

Error Handling Best Practices

✓Always check status codes before processing responses
✓Implement retry logic for 429 and 500 errors with exponential backoff
✓Log errors with context for debugging
✓Show user-friendly messages instead of technical error codes