When integrating with the Credit Clear API, it is important to build resilience into your client implementation. Following guidelines outline recommended best practices for handling errors, retries, and monitoring to ensure smooth operation of your integration.
Authentication
- Authorization Header: All API requests must include the Authorization header with a valid bearer token.
- Token Expiry: Tokens are valid for 24 hours. Implement automatic renewal logic before expiry to avoid authentication failures.
- Token Caching: Do not request a new token for every API call. Cache the token securely and reuse it until it expires. This prevents unnecessary load on the authentication server and helps avoid rate limit breaches or temporary blocks.
- Credential Storage: Store your
client_idandclient_secretsecurely using a secrets manager (e.g., Azure Key Vault). If credentials are exposed or compromised, contact [email protected] to request a new secret.
Rate Limits & Payload Constraints
- Rate Limit: Max 1000 requests per minute. Implement client-side throttling and usage monitoring to avoid hitting the rate limit.
- Payload Size:
- The maximum content length of JSON (POST/PUT) requests is 30 MB.
- The maximum content length of multipart/form-data request (attachment API) is 25 MB.
Attention: If any of the limits is breached, the request will be blocked
Error Handling Reference
| Status Code | Meaning | Recommended Action |
|---|---|---|
| 400 | Bad Request – invalid or missing parameters. | Validate and correct payload before retrying. |
| 401 | Unauthorized – invalid or expired token. | Refresh token or check credentials. |
| 403 | Forbidden – insufficient permissions. | Review access scopes or request elevated access. |
| 404 | Not Found – resource does not exist. | Confirm endpoint and identifiers. |
| 429 | Too Many Requests – rate limit exceeded. | Retry with exponential backoff and jitter. |
| 500 | Internal Server Error. | Retry with exponential backoff. |
| 503 | Service Unavailable – temporary downtime. | Retry with exponential backoff. |
Retry Logic
-
Idempotency:
BatchReferenceIdorReferenceIdto safely retry without duplication. -
Backoff Strategy: Apply exponential backoff with jitter for transient error such as
429,500or503. -
Retry Limits: Cap retries (e.g., max 3 attempts) to prevent cascading failures.
Monitoring & Alerts
-
Logging: Log all API calls and retry attempts with timestamps, error codes, and
BatchReferenceIdorReferenceId. Monitor logs actively for anomalies or repeated failures. -
Alerting: Trigger alerts for repeated 5xx errors, token failures, or rate limit breaches. For persistent issues, contact [email protected].