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. Use Playground to exercise success paths and error responses before you promote an integration.

---

✅ Complete Compliance Checklists

When compliance checklists are available for your application, complete the Security and Privacy items before requesting production access. Incomplete items can delay 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