Errors▾

Errors

One error envelope for every failure, with a stable machine-readable code.

Sendport uses conventional HTTP status codes. Every failure returns the same envelope.

Error envelope

{
  "error": {
    "type": "invalid_request_error",
    "code": "template_not_found",
    "message": "No approved template named 'order_shipped' in language 'ar'.",
    "param": "template.name",
    "doc_url": "https://sendport.tech/docs/errors#template_not_found",
    "request_id": "req_9f3c2a7b41de08c5b2e6d1a4"
  }
}

Status codes

Status	Meaning	Retry?
`200` / `202`	Success. `202` means queued for asynchronous delivery.	—
`400`	Malformed body or a parameter failed validation.	No — fix the request
`401`	Missing, malformed or revoked API key.	No
`403`	The key is valid but not permitted on this number.	No
`404`	No such resource, or it belongs to another account.	No
`409`	Conflicts with current state, e.g. a template name in use.	No
`422`	Rejected by WhatsApp — outside the session window, opted out.	No
`429`	Rate limited. See Rate limits.	Yes, with backoff
`5xx`	Something broke on our side.	Yes, with backoff

Error codes

Code	Status	What happened
`missing_api_key`	401	No `Authorization` header was sent
`invalid_api_key`	401	The key is malformed or has been revoked
`resource_not_found`	404	The path or id does not resolve
`invalid_phone_number`	400	`to` is not valid E.164
`template_not_found`	404	No approved template with that name and language
`template_param_mismatch`	400	Placeholder count does not match the approved body
`session_window_closed`	422	More than 24h since the contact's last message — send a template
`contact_opted_out`	422	The contact blocked the number or replied STOP
`media_too_large`	400	Beyond the per-type size cap
`number_not_connected`	403	The sending number is not connected or is disabled
`rate_limit_exceeded`	429	Too many requests in the window

Log the request id

request_id is also returned as the X-Request-Id header on successful calls. Logging it on both paths makes support requests solvable in one round trip.

PreviousSandbox NextRate limits