OTP SMS API Integration: Code Examples, Error Handling and Production Patterns

Start with an internal OTP service

Instead of calling the SMS provider directly from every login endpoint, create an internal OTP service or module. It accepts a business-level request such as “create verification challenge for user X”.

The service generates the code, stores the challenge and creates a messaging job. A separate messaging adapter communicates with the provider.

This structure keeps authentication logic independent of the SMS API vendor.

Define the request contract

A clean internal contract might contain user or transaction reference, destination, purpose, template identifier and expiry policy. Provider-specific fields should remain inside the adapter.

Validate the destination and purpose before generating the challenge. The request should also carry enough information to enforce tenant or application permissions.

Provider adapter design

The adapter should translate the internal message object into the provider's API format. It should handle authentication, request construction, response parsing and provider-specific error mapping.

Do not spread provider-specific status codes throughout the authentication service. Map them into internal categories such as accepted, temporary failure, permanent failure or unknown outcome.

Asynchronous submission

The OTP request endpoint should normally avoid waiting for final SMS delivery. Create the challenge and queue the notification quickly.

If the business requires the API to confirm provider acceptance before returning success, keep the timeout bounded. Never let an external provider hold the user's authentication request indefinitely.

Timeout and retry handling

A network timeout creates uncertainty. The provider may have accepted the request even though the response did not reach the application.

Blindly retrying can create duplicate OTP messages. Use idempotency support if available or reconcile uncertain submissions before deciding to retry.

Callback processing

A delivery webhook should validate the incoming event, locate the provider message ID and update the message record. The callback handler should be fast and idempotent.

Do not make the user's verification request depend on the callback being processed first. A valid OTP can be entered independently of delivery-report timing.

Testing provider errors

Create tests for authentication errors, validation failures, rate limiting, timeouts, malformed responses and duplicate callbacks.

Use a mock provider so that developers can simulate these conditions without sending real SMS. Include automated tests for the internal status mapping.

Deployment configuration

Keep API endpoints, credentials, sender configuration and rate limits outside application source code. Separate test and production settings.

A deployment should be able to change the provider credential without requiring a source-code change. Secret rotation should be documented and tested.

Observability

Add structured logs containing challenge ID, business reference, provider message ID and timestamps. Avoid logging the actual OTP.

Metrics should cover generation, queueing, provider submission, delivery and verification success. These measures help distinguish an authentication problem from a messaging problem.

Safe failure behaviour

If the SMS provider fails, the authentication system should return a controlled result and offer a resend path according to policy. It should not reveal provider credentials, internal errors or unnecessary account information.

For critical systems, document whether an alternative authentication factor is available.

Integration handoff checklist

Before handing the integration to another developer, document the provider contract, internal request model, message-state mapping, challenge lifecycle, retry policy, callback endpoint and testing procedure.

A good handoff should allow another engineer to understand the complete flow without reading every line of application code.

Provider-neutral OTP module

A provider-neutral OTP module makes the code-generation and verification workflow independent of the SMS vendor. The module creates a challenge and hands a message object to the messaging adapter.

If the provider changes, only the adapter and configuration should need substantial modification. This is especially valuable for software vendors supporting multiple customers with different messaging providers.

Error taxonomy

Create an internal error taxonomy rather than passing raw provider errors directly to the user interface. Authentication errors can be categorized as invalid request, rate limited, temporary provider failure, permanent destination failure or unknown submission state.

The user should receive a safe, understandable response while the engineering logs retain the technical details needed for diagnosis.

Idempotent verification

Verification endpoints should handle repeated requests safely. Once a challenge is consumed, another request using the same code should not authorize the operation again.

The database operation that checks validity and marks the challenge as consumed should be atomic. This is particularly important when two verification requests arrive almost simultaneously.

API contract testing

Use automated contract tests to ensure that provider request and response formats remain compatible. Include authentication headers, required fields, status mapping and delivery callback schemas.

Run these tests when changing provider versions or upgrading the messaging adapter.

Production release strategy

Deploy OTP changes gradually where possible. Monitor request volume, provider acceptance, verification success and error categories immediately after release.

If the provider integration changes, retain the ability to disable the new adapter or route traffic through the previous implementation while the issue is investigated.

Testing under concurrency

Run concurrent verification tests to confirm that a single OTP cannot authorize two requests. Also test concurrent resend operations to verify that the challenge lifecycle behaves as designed.

Race conditions may not appear during manual testing because real users rarely submit identical requests at exactly the same time. Automated concurrency tests are therefore valuable.

Monitoring release impact

After deploying an OTP integration change, compare verification success and provider error rates with the previous baseline. Watch for changes in resend frequency and time-to-verification.

A technically successful deployment can still damage the customer journey if messages become slower or the interface receives different status information.

Provider migration

If the SMS provider changes, keep the OTP challenge and verification database unchanged. Replace the provider adapter and test submission, callback handling and status mapping.

Run the new provider in a controlled environment before production. If both providers are temporarily active, make routing rules explicit so that one request does not accidentally send duplicate codes through both paths.

API documentation

Document the internal OTP API separately from the provider API. Developers using the authentication service should not need to understand provider-specific headers or response codes.

The documentation should explain request fields, error categories, challenge lifecycle, expiry, resend rules and verification behaviour. This makes the service easier to adopt safely.

Example integration sequence

A clean sequence is: authentication endpoint requests a challenge; OTP service creates it; messaging adapter queues the SMS; worker submits it; provider reference is stored; user submits the code; verification service checks the challenge; database atomically marks it consumed; authentication continues.

Each transition should have a clear owner and failure state. This makes production debugging much easier than a single synchronous function containing the entire workflow.

Rollback planning

If a new provider adapter or OTP release causes verification failures, the team should know how to return to the previous version without invalidating legitimate active challenges.

Keep challenge storage compatible across application versions where possible. Treat database changes carefully because authentication state is often short-lived but business-critical.

Final production scenario

Run the integration against a mock provider that returns success, timeout, rate-limit, malformed-response and delivery-callback scenarios. Confirm that the internal OTP service remains provider-independent and that deployment configuration can be changed without code edits.

Final operational handoff

Document the internal API contract, provider adapter, error taxonomy, callback schema, deployment variables and rollback procedure. Keep provider-specific implementation details isolated so future developers can change vendors safely.

Final readiness check

Verify provider abstraction, timeout handling, callback processing, concurrency safety, deployment configuration and rollback before production.

Production verification

Run one successful verification and one controlled provider failure after deployment. Confirm that the monitoring dashboard records both outcomes and that the rollback procedure remains available.