Errors and Status Codes

Mersal's API follows standard REST conventions: 2xx for success, 4xx for client errors (something about your request needs fixing), and 5xx for server errors (something went wrong on Mersal's side — safe to retry after a delay).

Common error responses

403 — Authentication and subscription errors

Returned by the channel-sending endpoints (sms/send, whatsapp/send, email/send, and their GET /api/get/{channel}/{id?} counterparts) when the API key is missing, invalid, or the account's subscription has expired.

{
  "status": "error",
  "error": "Invalid Api Key"
}

422 — Validation failure

Returned when the request body fails validation — for example, a missing contact array, an empty contact array, a missing number/email/message/subject field, or a malformed schedule_at value. This follows Laravel's standard per-field validation error format: errors is an object keyed by field path, each value an array of human-readable messages for that field.

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "contact.0.number": ["The contact.0.number field is required."],
    "contact.0.message": ["The contact.0.message field is required."]
  }
}

General conventions

• 2xx — the request succeeded. Sends typically return success: true (or status: "success") with a data payload describing what was queued or scheduled.
• 4xx — something about the request needs fixing on your end: bad or missing authentication (403), or invalid request data (422).
• 5xx — an unexpected server-side error. These are uncommon; if you see one, it's safe to retry after a short delay.

See also

• Authentication — how to avoid 403 errors.
• Rate Limits — throttling behavior on the AI Gateway and channel gateways.