The SDK and Auth Questions That Determine Whether Developers Adopt Your API

Handle it automatically, and make the failure mode visible when refresh itself fails. A developer who has to manually detect an expired token and re-authenticate on every integration will get it wrong somewhere, usually by catching the expiry error too broadly and silently swallowing a real auth failure along with it.

When the SDK does handle refresh, surface a clear, distinct error when refresh itself is rejected, expired refresh token, revoked grant, rather than retrying silently forever or failing with the same generic error as every other problem. Picture a long-running background job that holds a token for hours: if refresh happens silently and correctly, the job never notices; if refresh starts failing because the grant was revoked, the job needs a distinct, actionable error rather than a generic timeout that looks like a network blip.

"Access denied" tells a developer nothing about whether they used the wrong scope, an expired token, or a genuinely unauthorized action, and they'll spend an hour guessing. You can be specific about the caller's own request without revealing information about other tenants' data: say which scope was required, not what the underlying record actually contains.

The rule that holds up well: a 403 response should always let the caller understand what they'd need to change about their own request, never what exists on the other side of a boundary they don't have access to.

A shared, long-lived API key passed around a team for local development is exactly the kind of secret that ends up committed to a repo or pasted into a support ticket. Give each developer their own short-lived local credential, scoped narrowly and easy to regenerate, so a leaked local-dev key is a minor inconvenience rather than an incident.

Make this the path of least resistance in your SDK's quickstart, not an advanced option buried in the documentation, since developers default to whatever the getting-started guide shows them. A common mistake is documenting the secure path as an optional, advanced section while the copy-pasteable quickstart snippet uses a long-lived shared key, since almost everyone just runs the snippet and never reads the advanced section at all.

A developer who can't immediately tell, from the credential itself, whether they're pointed at sandbox or production data is one accidental script run away from a real incident. Prefix or otherwise visibly mark sandbox credentials so they're unmistakable in logs, error messages, and a developer's own terminal history.

This matters most for exactly the situation it sounds unlikely: a developer testing a batch script locally against what they believe is sandbox data, using a credential that was actually issued for production. A visibly distinct credential format catches this before it becomes a support ticket rather than after.

Put the machine-readable specifics, error code, the scope or permission involved, whether it's retryable, directly in the error object your SDK returns, since that's what a developer's code actually branches on. Put the narrative explanation, why this error exists and how to fix it, in documentation the error links to.

An SDK that returns a bare string message forces every integrator to write their own fragile string-matching logic to handle different failure types, which breaks the moment you change the wording. Treat the error code itself as part of your public contract once it ships: changing an existing code's meaning, or reusing it for a different failure case later, breaks every integrator's error-handling branch silently, with no compile-time warning that anything changed.

A useful SDK error object carries:

• A stable machine-readable error code that a developer's code can branch on, instead of a bare message string.
• The scope or permission involved in the failure, so the developer knows what to request instead of guessing.
• Whether the error is retryable, so callers don't loop on a denial that will never succeed.
• A link to documentation that explains why the error exists and how to fix it, keeping the narrative out of the object.