Best Practices
Follow these best practices to build reliable, secure, and user-friendly integrations that scale with your users.
API Usage
Respect Rate Limits
Implement exponential backoff when you hit rate limits. Cache responses when possible to reduce API calls.
Handle Pagination
Use cursor-based pagination for large result sets. Don't request more data than you need.
Secure Token Storage
Store access tokens and refresh tokens securely. Never log tokens or expose them in client-side code.
Webhook Handling
Respond quickly
Return a 2xx response within 5 seconds. Queue processing for later if needed.
Implement idempotency
Store webhook IDs to handle duplicate deliveries gracefully.
Verify signatures
Always validate webhook signatures before processing payloads.
Handle failures
Log failed processing and implement retry mechanisms.
Error Handling
| Error Type | Recommended Action |
|---|---|
| 400 Bad Request | Check your request parameters and payload format |
| 401 Unauthorized | Refresh the access token and retry |
| 403 Forbidden | Request additional scopes from the user |
| 404 Not Found | Verify the resource ID exists |
| 429 Too Many Requests | Implement exponential backoff |
| 500 Server Error | Retry with exponential backoff, contact support if persistent |
User Experience
Clear onboarding
Guide users through setup with clear instructions and progress indicators.
Helpful error messages
Show actionable error messages that help users resolve issues.
Sync status
Show sync status and last successful sync time.
Easy disconnection
Provide a clear way for users to disconnect your app.