Motion 5Book a demo

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.

Header
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.

Error response
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

400
Bad request
The request couldn't be read: invalid_json, invalid_idempotency_key, missing_file, empty_message, message_too_long, unsupported_file_type, file_too_large.
401
Unauthorized
unauthorized: the API key is missing, unknown or revoked.
403
Forbidden
live_key_required: conversations need a live key.
404
Not found
not_found: no such code, conversation, message or endpoint for your bank. media_expired: WhatsApp no longer has the file.
409
Conflict
The request is fine but can't happen now: window_closed, assigned_to_someone_else, no_open_handoff, no_number, idempotency_key_in_use.
422
Invalid
A field is wrong: invalid_phone, invalid_ttl, invalid_length, invalid_request, invalid_agent, invalid_status, invalid_limit, idempotency_key_reused.
429
Too many
too_soon or rate_limited. The Retry-After header says how many seconds to wait.
502
WhatsApp
send_failed or whatsapp_refused: WhatsApp didn't take the message. The message says why.
500
Our side
internal_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 gets 409 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, 500 and 502, waiting longer each time (for example 1, 2, then 4 seconds), with the same Idempotency-Key.
  • For 429, wait at least the Retry-After seconds.
  • Don't retry other 4xx errors unchanged: fix the request first.

Rate limits

Codes are limited per phone number (see OTP limits). Beyond that we ask for fair use; if you expect bursts of more than a few requests per second, tell us before launch.