Using the API well

Errors

Every error has the same shape, a stable code you can branch on, and a docUrl that links to its entry on this page.

error response

HTTP/1.1 422 Unprocessable Entity

{
  "error": {
    "code": "SERVICE_WINDOW_CLOSED",
    "type": "policy_error",
    "message": "Free-form messages require an open 24-hour service window.",
    "retryable": false,
    "retryAfterSeconds": null,
    "docUrl": "https://shipmsg.com/docs/errors#SERVICE_WINDOW_CLOSED",
    "requestId": "req_FjLKGlzDxsiDKsIz",
    "providerCode": 131047,
    "details": [{ "path": "type", "issue": "…" }]
  }
}

retryable is the only thing that says whether retrying can help. When it is true, wait retryAfterSeconds (or the Retry-After header) and retry with the same Idempotency-Key.
providerCode is WhatsApp’s own error code, when the refusal came from WhatsApp.
details lists each invalid field for validation errors.
Quote requestId when you contact support; it also finds the call in your request log.

The same list is available as JSON at GET /v1/errors (no key needed). Failed messages carry the same codes in data.error on message.failed.

API error messages below are shown exactly as returned by the API. The explanations are translated.

Authentication

The request could not be tied to a valid credential. Fix the key or signature; retrying unchanged will fail again.

AUTHENTICATION_ERROR

HTTP 401authentication_errorNot retryable

Authentication failed.

The API key is missing, mistyped, revoked, or used from an address outside its allow-list. Send Authorization: Bearer <secret> with the full secret shown when the key was created.

API_KEY_DISABLED

HTTP 401authentication_errorNot retryable

The API key is disabled.

The key was disabled in the console or by an administrator. Re-enable it or create a new key.

SIGNATURE_REQUIRED

HTTP 401authentication_errorNot retryable

This key requires request signing.

This key is configured to require signed requests. Turn on request signing in your SDK (the signing option) or add the X-ShipMessages-Key, -Timestamp, -Nonce and -Signature headers.

SIGNATURE_INVALID

HTTP 401authentication_errorNot retryable

The request signature is invalid.

The signature did not match. Sign the exact bytes you send, with the path and query in canonical order, and keep your clock within 5 minutes of real time.

SIGNATURE_REPLAYED

HTTP 401authentication_errorNot retryable

The request signature was already used.

The nonce was already used. Every signed request needs a new random nonce; the SDKs generate one per attempt.

SIGNING_UNAVAILABLE

HTTP 503authentication_errorRetryable

Request signing verification is temporarily unavailable.

Signature checking is briefly unavailable. Retry after a short wait; nothing was processed.

CAPTCHA_REQUIRED

HTTP 401authentication_errorNot retryable

A completed challenge is required before another sign-in attempt.

Several failed sign-ins in a row: the next sign-in must include a solved challenge.

CAPTCHA_INVALID

HTTP 401authentication_errorNot retryable

The challenge response could not be verified.

The challenge answer was rejected or expired. Solve a new challenge and sign in again.

Permission

The credential is valid but may not do this. Use a key or role with the needed permission.

AUTHORIZATION_ERROR

HTTP 403authorization_errorNot retryable

Insufficient permission.

The key or user lacks the permission (scope) this endpoint needs, or the resource belongs to another account or environment. Check the key's scopes and that a sandbox key is used with sandbox resources.

STEP_UP_REQUIRED

HTTP 403authorization_errorNot retryable

Step-up authentication is required.

This action is sensitive and needs a fresh second-factor confirmation from a signed-in user. It cannot be done with an API key alone.

APPROVAL_REQUIRED

HTTP 403authorization_errorNot retryable

This action requires approval.

Your account requires a second person to approve this action. It has been queued for approval; it runs once approved.

Invalid request

The request itself is wrong. Read details for the field and fix the request before sending it again.

VALIDATION_ERROR

HTTP 400validation_errorNot retryable

The request is invalid.

A field is missing, has the wrong type or is out of range. details lists each problem as a field path and an issue.

NOT_FOUND

HTTP 404validation_errorNot retryable

Resource not found.

No such resource in this account and environment. Check the SID, and that sandbox and live resources are not mixed.

METHOD_NOT_ALLOWED

HTTP 405validation_errorNot retryable

This method is not supported for this path.

This path exists, but does not support the requested HTTP method. Use a method listed in the Allow response header and the API reference; do not retry the same method.

CAPABILITY_UNAVAILABLE

HTTP 400validation_errorNot retryable

The sender does not have this capability.

The sender cannot send this kind of message (for example a Flow or a product message) until the capability is enabled on its WhatsApp Business Account.

MEDIA_NOT_READY

HTTP 400validation_errorRetryable

The media is not ready yet.

The uploaded media is still being scanned or processed. Wait until its state is READY, then send.

MEDIA_REJECTED

HTTP 400validation_errorNot retryable

The media was rejected.

The media failed the safety scan or is an unsupported type or size. Upload a different file.

RECIPIENT_ADDRESSING_UNSUPPORTED

HTTP 400validation_errorNot retryable

This recipient addressing is not supported for this message.

This message type cannot be sent to that kind of address (for example a username instead of a phone number). Address the recipient by phone number.

RECIPIENT_USERNAME_INVALID

HTTP 400validation_errorNot retryable

The recipient username is invalid.

The WhatsApp username is not in a valid format.

STATUS_CALLBACK_NOT_VERIFIED

HTTP 422validation_errorNot retryable

The status callback endpoint is not verified.

A per-message status callback must point at a webhook endpoint that has passed verification. Verify the endpoint first.

TEMPLATE_NAME_LOCKED

HTTP 400validation_errorNot retryable

The template name is locked.

A template with this name was deleted recently; WhatsApp does not allow reusing the name for 30 days. Pick another name.

TEMPLATE_CAP_REACHED

HTTP 400validation_errorNot retryable

The template cap has been reached.

The WhatsApp Business Account has reached its template limit. Delete unused templates.

Idempotency

The Idempotency-Key clashes with another request. See the idempotency guide.

IDEMPOTENCY_KEY_REUSED

HTTP 409idempotency_errorNot retryable

Idempotency key reused with a different request.

The Idempotency-Key was already used within 24 hours for a different request body or endpoint. Use a new key for a new request.

IDEMPOTENCY_IN_PROGRESS

HTTP 409idempotency_errorRetryable

A request with this idempotency key is still in progress.

The first request with this key is still running. Wait a moment and retry with the same key; you will receive its result.

Rate limits

Too many requests. Wait retryAfterSeconds (also in the Retry-After header), then retry.

RATE_LIMITED

HTTP 429rate_limit_errorRetryable

Rate limit exceeded.

A rate limit was exceeded. Wait retryAfterSeconds, then retry. The RateLimit-Policy header names the limit you hit.

PROVIDER_RATE_LIMITED

HTTP 429rate_limit_errorRetryable

The provider is rate limiting this sender.

WhatsApp is throttling this sender. The message is retried automatically when queued; for direct calls, wait and retry.

Policy and account state

The request is well formed, but a rule stops it: account state, consent, a WhatsApp policy or a limit. Change the situation, not the request.