1. Payload handling

Applications must handle new or optional fields in JSON payloads gracefully:

• Don't break when additional fields are introduced.Ignore fields you don't need.
• Never rely on field ordering in JSON.
• Validate required fields and fail fast with clear errors when required data is missing.

2. HTTP status codes

Treat status codes as signals and follow these guidelines:

1. 4xx - client errors
   Indicates a problem with the request. Do not retry automatically; inspect and fix the request.
2. 429 Too Many Requests
   Always respect the Retry-After header before sending further requests.
3. 5xx - server errors
   Indicates temporary server-side issues. Use exponential backoff with jitter when retrying.
4. Timeouts
   Treat timeouts as potentially recoverable; retry with backoff rather than immediate repeated attempts.

3. Rate limiting & efficiency

• Do not exceed published rate limits.
• Prefer bulk/list endpoints over repeatedly calling single-item endpoints.
• Cache responses where appropriate to reduce unnecessary requests (respect cache headers).

4. Security & authentication

• Keep API keys and credentials secure; do not hardcode them in public repositories.
• Rotate credentials regularly. In the Developer Portal: Applications → Edit → create new key, then delete the old key when unused.
• Follow least-privilege principles: issue keys with only the scopes/permissions required.

5. Versioning & compatibility

• Always check API versioning information and release notes; update clients according to published deprecation schedules.
• Rely only on behavior documented in the official API docs. Undocumented behaviours may change without notice. Examples to avoid relying on:
• Specific wording of undocumented error messages.
• Default values not explicitly documented.
• Internal headers or metadata that appear in responses but are not part of the public contract.

6. General reliability

• Build clients to tolerate short outages or degraded performance.
• Log errors with enough detail to support troubleshooting (status code, response body, and requestId when present).
• Instrument retries, failures and latencies for observability and alerting.