Best practices

​

Use HTTPS

​

Handle errors and status codes

• Check the HTTP status code on every response (e.g. 2xx success, 4xx client error, 5xx server error).
• Read the response body on errors; it often contains a message or error code to help you retry or fix the request.
• Implement retries with backoff for transient failures (e.g. 429 Too Many Requests, 503 Service Unavailable).

​

Respect rate limits

• Throttle your requests and avoid bursts; use exponential backoff when you hit limits.
• Cache responses where it makes sense to reduce the number of calls.

​

Authenticate correctly

• Store tokens securely (e.g. environment variables or a secrets manager) and never commit them to source control.
• Send the token in the Authorization header as specified (e.g. Bearer <token>).
• Refresh or renew tokens before they expire to avoid failed requests.

​

Use pagination

• For list endpoints, use the provided pagination parameters (e.g. page, limit, or cursor) instead of fetching everything at once.
• Follow the documented page size limits to avoid timeouts and unnecessary load.

​

Use appropriate HTTP methods and URLs

• Use GET for reading, POST for creating, PUT/PATCH for updating, and DELETE for removing resources.
• Prefer resource-oriented URLs (e.g. /users/123) and avoid unnecessary query parameters for identifiers.

​

Logging and monitoring

• Log request/response metadata (e.g. endpoint, status code, request ID) for debugging, without logging full credentials or sensitive payloads.
• Monitor success rates, latency, and error types so you can react to issues quickly.