Getting started
Keys, errors and retries
How to authenticate, what errors look like, and how to retry a request without sending a code or a message twice.
API keys
Send your key as a Bearer token on every request. Your bank's admins create and revoke keys at Developers; a key is shown once when it's made, and Motion 5 keeps only a hash of it.
Authorization: Bearer m5_live_7Qe9…m5_test_…keys work in test mode: nothing is sent and codes are always zeros.m5_live_…keys send real WhatsApp messages and can read conversations.- Use a separate key per system (your app backend, your helpdesk), so you can revoke one without breaking the others.
- Revoking a key stops it at once. Requests with a missing, unknown or revoked key get a 401.
Errors
Successful requests answer with a 2xx status. Anything else carries an error object with a stable code for your program and a message for people. Codes don't change; messages may be reworded.
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{ "error": { "code": "invalid_phone", "message": "phone must be a valid number, like +2348031234567 or 08031234567." } }Statuses and codes
400invalid_json, invalid_idempotency_key, missing_file, empty_message, message_too_long, unsupported_file_type, file_too_large.401unauthorized: the API key is missing, unknown or revoked.403live_key_required: conversations need a live key.404not_found: no such code, conversation, message or endpoint for your bank. media_expired: WhatsApp no longer has the file.409window_closed, assigned_to_someone_else, no_open_handoff, no_number, idempotency_key_in_use.422invalid_phone, invalid_ttl, invalid_length, invalid_request, invalid_agent, invalid_status, invalid_limit, idempotency_key_reused.429too_soon or rate_limited. The Retry-After header says how many seconds to wait.502send_failed or whatsapp_refused: WhatsApp didn't take the message. The message says why.500internal_error. Safe to retry with the same Idempotency-Key.Idempotency
Networks drop responses. If a request to send a code or a message times out, you can't tell whether it went through. Send an Idempotency-Key header on POST requests, and if you send the same request again with the same key, Motion 5 answers with the first response instead of acting twice.
curl https://motion5.dev/v1/otp/send \
-H "Authorization: Bearer $MOTION5_KEY" \
-H "Idempotency-Key: 6f1d9c2e-4b1a-4f7e-9a51-3c2d1e0f9b8a" \
-H "Content-Type: application/json" \
-d '{ "phone": "08031234567" }'- Use a new key for each action, such as a UUID. Keys can be up to 255 characters.
- A replayed response has the same status and body as the first, plus the header
Idempotent-Replayed: true. - The same key with a different body or path is refused with
422 idempotency_key_reused. While the first request is still running, a repeat gets409 idempotency_key_in_use: wait a moment and try again. - Keys last 24 hours, and test and live keys have separate key spaces.
- Server errors (5xx) aren't remembered, so a retry runs the request again.
Retrying safely
- Retry on network errors,
429,500and502, waiting longer each time (for example 1, 2, then 4 seconds), with the same Idempotency-Key. - For
429, wait at least theRetry-Afterseconds. - Don't retry other 4xx errors unchanged: fix the request first.
Rate limits