1. Interpret HTTP 202 correctly
HTTP 202 means the platform accepted your request into its queue. It does not confirm transmission or receipt on a phone. Store the returned message identifier and follow its status or events received by your endpoint.
The contract distinguishes message.submitted, message.sent and message.delivered events. A reconciliation state indicates uncertainty to resolve, not permission to create another send immediately. Platform processing time and external carrier transmission time are also separate measurements.
2. Keep one key per logical request
Persist a stable idempotency key with the business operation before calling the API. To replay after an uncertain network response, reuse the same key and content. Generating a new key for every retry represents another request and can send a second SMS.
Keys contain 16–100 alphanumeric characters, hyphens or underscores. Do not build them from a phone number, message text or OTP. If business content changes, explicitly treat it as a new operation rather than silently changing a retry.
POST /v1/messages
Authorization: Bearer <server-side key>
Content-Type: application/json
Idempotency-Key: order_update_example_a3. Handle uncertain responses and limits
A timeout can occur after acceptance. Reconcile the known outcome and reuse the same key for a replay permitted by the contract. Avoid immediate, unlimited retry loops and retain the correlation identifier for diagnosis.
For rate limits, respect Retry-After when provided. Check the subscription, remaining allowance and daily maximum too. API access does not add units or capacity beyond your plan.
4. Verify and deduplicate callbacks
Configure a server-side HTTPS endpoint. Verify the signature against the raw request body, timestamp and signing secret specified in the reference before trusting content. Use the downloadable verification helper instead of inventing an algorithm variant.
Persist processed event identifiers. An unavailable endpoint may receive retries, so receiving an event more than once must not repeat its business action. A callback must not trigger a replacement SMS for the original request.
Return success after durably recording the event or handing it off for processing. Endpoint verification and attempt history distinguish a receiver-configuration problem from an SMS event still pending.
For secret rotation, temporarily accept both secrets, add and verify the replacement destination, then disable the old one. Deduplicate event IDs across the overlap. A request already in progress may still arrive after disabling. Exhausted deliveries and events missed while a destination is disabled are not replayed: reconcile known message IDs with GET /v1/messages/{id}, without resending their SMS.
5. Keep OTP verification in your application
Your application generates the OTP, sets expiry, limits requests and attempts, and verifies the entered code. SMSMarocPro transports the message. A sending status or callback never proves that the user entered the right code.
Keep API keys and webhook secrets in server-side secret storage. Do not include OTPs, phone numbers or message bodies in marketing analytics or URLs. Test processing with simulated events before contacting real recipients. Immediate receipt is not guaranteed.