Best practices

Retries

Transient failures happen, so build retries in from the start.

• Retry on 429, 500, 502, 503, 504 and network timeouts.
• Honor Retry-After whenever it's present.
• If there's no Retry-After, use exponential backoff with jitter, for example min(cap, base * 2^attempt) + random(0, base), and give up after a few attempts.
• Don't retry 400, 403, 404 or 409. The request has to change first.

In .NET, Microsoft.Extensions.Http.Resilience gives you a sensible standard pipeline:

services.AddHttpClient("AgencyMax", c => c.BaseAddress = new Uri("https://api.agencymax.example.com/agency-management/"))
    .AddStandardResilienceHandler();

Idempotency

Know which writes are safe to repeat:

Operation	Safe to retry?
GET	Yes.
PATCH, PUT	Yes. Sending the same body again gives the same result.
DELETE	Yes. A repeat may return 404.
Agency Management POST /certifications	Yes. It's an add-or-update operation that matches existing certifications. See Certifications.
Agency Management POST /agents	No. A retry after a timeout could register a duplicate agent. Before retrying, look the agent up by governmentIdentifier, npn or email.
Agent Onboarding POST /applications	Mostly. A duplicate government identifier returns 409.

Keep data in sync efficiently

• Subscribe to webhooks to hear about changes as they happen.
• Use modifiedSince on GET /agents for incremental catch-up syncs.
• Cache reference data such as jurisdictions, certification types and pay statuses, and refresh it occasionally.

Security

• Keep client secrets, subscription keys and webhook secrets in a secret store. Never commit them to source control.
• Never call the APIs straight from a browser or mobile app with your credentials. Go through your own backend.
• Request the smallest set of scopes you need.
• Verify the signature of every webhook you receive. See Receiving webhooks.
• Treat government identifiers, tax data and bank details as highly sensitive.

Logging and support

• Log the request method, URL (without secrets), status code and any traceId in error responses.
• When you contact support, include the environment, tenant, timestamp (UTC) and traceId.