Common Errors

This page covers the errors you're most likely to hit while integrating with Mersal's API, with what each one actually means and how to fix it. For the full reference of status codes and response conventions, see Errors and Status Codes.

403 — "Invalid Api Key"

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

This means the Api-key header (or fallback api_key query/body parameter) is missing, misspelled, or doesn't match a real key on your account.

How to fix it:

• Double-check the header name is exactly Api-key — not Authorization, not apikey, not X-Api-Key. Channel-sending endpoints (/api/sms/send, /api/whatsapp/send, /api/email/send) don't use Bearer-token auth; that style is reserved for the AI Gateway only.
• Confirm you copied the key from your account's API key page in the dashboard, with no extra whitespace or truncation.
• If you regenerated your API key recently, make sure every integration using the old key has been updated — see API Key Management.

See Authentication for the full auth contract.

403 — "Your Subscription Is Expired! Buy A New Plan"

{
  "status": "error",
  "error": "Your Subscription Is Expired! Buy A New Plan"
}

This is a different failure from an invalid key — your API key is valid, but your account's plan/subscription has lapsed. Channel-sending endpoints require an active subscription regardless of key validity, so every send request returns this until the plan is renewed.

422 — "Validation failed"

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

This is Laravel's standard validation error shape: message tells you validation failed overall, and errors is an object keyed by field name, where each value is an array of specific problems with that field.

How to read it:

• The keys tell you exactly which field failed — contact means the whole array is missing; contact.0.number (or contact.*.number across multiple entries) means a specific recipient in the array is missing its number/address.
• Fix the fields named in errors first — they're the authoritative list of what's wrong with the request, not a generic failure.

Common causes:

• Sending an empty or missing contact array — every send endpoint requires at least one recipient.
• A recipient object missing the field the channel expects (number for SMS/WhatsApp, an email address for Email).
• Malformed JSON, or the wrong Content-Type header, causing fields to arrive empty even though you sent them.

General debugging approach

1. Read the HTTP status code first — 403 is an auth/billing problem, 422 is a request-shape problem, and anything in the 5xx range points to a platform-side issue worth reporting.
2. Read the error or message field in the JSON body — Mersal's error responses are meant to be read directly, not just used as a boolean success/fail flag.
3. For 422 specifically, check the errors object field-by-field rather than guessing at what's missing.
4. If the request looks correct and still fails, check Message Delivery Issues — some failures happen after validation passes, at the gateway or provider level.