API Best Practices

Follow these guidelines to build robust, efficient integrations with the EC-Permit API.

Error Handling

• Check response status codes
• Parse error messages from response body
• Implement retry logic for transient failures
• Log errors for debugging

// Error response structure
{
  "error": {
    "code": "validation_error",
    "message": "Invalid form data",
    "details": [
      { "field": "q_work_date", "error": "Required field missing" }
    ]
  }
}

Rate Limiting

• Default limit: 100 requests per minute per API key
• Check X-RateLimit-Remaining header
• Implement exponential backoff on 429 responses
• Batch operations when possible

Efficient Pagination

• Use cursor-based pagination for large datasets
• Request only the page size you need
• Cache results when appropriate
• Use filters to reduce dataset size

Idempotency

• Include Idempotency-Key header on POST requests
• Use unique keys (UUID recommended)
• Same key returns same result within 24 hours

POST /v1/projects/proj_123/forms
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Security

• Store API keys in environment variables
• Never log or expose keys in error messages
• Use HTTPS exclusively
• Validate webhook signatures
• Implement proper access controls in your app

Webhook Best Practices

• Process webhooks asynchronously
• Return 200 quickly, process later
• Handle duplicate deliveries idempotently
• Monitor webhook failures
• Set up alerting for disabled webhooks

API Versioning

• Always include version in URL (/v1/)
• Monitor deprecation notices in response headers
• Test against new versions before upgrading
• Subscribe to API changelog updates

Integration Checklist