Best Practices

Follow these guidelines to build secure, reliable, and compliant applications on the Sri Lanka DPI Developer Portal.

---

🔒 Secure Your API Keys

Never commit API keys to version control. Use environment variables and a secrets manager (e.g., HashiCorp Vault, AWS Secrets Manager). Rotate your key immediately if you suspect it has been compromised.

# ✅ Store in environment variables
export DPI_API_KEY="your-key-here"

# ❌ Never hardcode in source code
const apiKey = "sk-live-abc123...";

---

⏱️ Respect Rate Limits

Implement exponential back-off and respect the rate limits returned in response headers. Exceeding limits may temporarily suspend your sandbox access.

Retry-After: 30
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0

---

📌 Version Your Integrations

Always pin to a specific API version in your integration. Subscribe to the Changelog → to be notified of breaking changes before upgrading.

# ✅ Pin to a specific version
GET /v1/apis/{apiId}/versions/2.0.0/endpoints

# ❌ Avoid using 'latest' in production
GET /v1/apis/{apiId}/versions/latest/endpoints

---

🧪 Use the Sandbox First

Always validate your integration in the sandbox environment before requesting production access. Test all edge cases including error responses, rate limit handling, consent flows, and 404s — use the Test Scenarios Panel to cover them systematically.

---

✅ Complete Compliance Checklists

Ensure each application completes the Security Checklist and Privacy Checklist before going live. Incomplete compliance items will block your production approval.

---

🚨 Handle Errors Gracefully

Implement proper error handling for all API calls. Display user-friendly messages and log technical details server-side — never expose raw API errors or stack traces to end users.

HTTP Code	Meaning	Recommended action
401	Token expired or missing	Refresh token and retry
403	Insufficient scope	Check your OAuth scopes
422	Invalid request body	Validate against OpenAPI schema
429	Rate limit exceeded	Back off and retry after Retry-After
5xx	Platform error	Check Platform Status, retry with back-off