Skip to content

Errors

When a request fails, the API answers with an HTTP status and a body of type application/problem+json (RFC 9457). Branch on code, not on detail: codes are stable, while the human-readable text may change.

{
"type": "https://docs.smsfabric.com/errors/validation_failed",
"title": "Bad Request",
"status": 400,
"detail": "The request is invalid",
"code": "validation_failed",
"errors": [
{ "field": "to[1]", "message": "must be a valid E.164 phone number" },
{ "field": "metadata", "message": "must be at most 4096 bytes of JSON" }
],
"requestId": "req_u7x0a3d6g9j2m5p8s1v4y7b0"
}
Field Meaning
type A URI that names the problem.
title The HTTP status text.
status The HTTP status, repeated.
detail What went wrong, for a person. May change wording.
code Stable machine code. Listed below.
errors Present on validation errors: one entry per invalid field. Nested fields use dots (quietHours.start), array items use brackets (to[1]).
params Present on plan refusals: the values behind detail (the plan, the limit, what was limited, when it resets), so you can word the error yourself. See Plan errors.
requestId Quote it when you contact support.

Unknown fields in a request body are rejected too (validation_failed, with a message such as property foo should not exist), so a typo in a field name never fails silently.

Terminal window
curl -s https://api.smsfabric.com/v1/messages \
-H "X-Api-Key: $SMSFABRIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"to": "+2010", "body": "Hello"}'
# {"type":"https://docs.smsfabric.com/errors/validation_failed","title":"Bad Request","status":400,
# "detail":"The request is invalid","code":"validation_failed",
# "errors":[{"field":"to[0]","message":"must be a valid E.164 phone number"}],"requestId":"req_…"}
Status Retry?
400, 401, 403, 404, 413, 415, 422 No. Fix the request, the key or the data first.
409 idempotency_in_progress Yes, after a second, with the same Idempotency-Key. Other 409 codes: no.
429 rate_limited, 429 too_many_listeners Yes, after Retry-After seconds (see Rate limits).
429 quota_exceeded No. The plan’s daily or monthly allowance is used up; sending works again at params.resetsAt.
503 maintenance Yes, after Retry-After seconds.
500, 503, network errors and timeouts Yes, with exponential backoff and the same Idempotency-Key (see Idempotency).

The Node SDK does this for you: it retries network errors, 429, 5xx and 409 idempotency_in_progress twice by default, honouring Retry-After. Other 409 codes are thrown at once, and the error’s retryAfter holds the wait in seconds. It never retries 429 quota_exceeded.

Status code Meaning What to do
400 validation_failed One or more fields are invalid or unknown. errors[] lists them. Fix each listed field.
400 bad_request The body is not valid JSON, or another malformed request. Send valid JSON with Content-Type: application/json.
400 invalid_cursor The cursor is not one the API returned. Pass nextCursor exactly as received.
400 invalid_idempotency_key The Idempotency-Key has invalid characters or length. Use 1 to 255 characters of A–Z a–z 0–9 _ - : ..
400 template_invalid A template or campaign body has an unknown variable or stray braces. errors[] lists them. Use only {{first_name}}, {{last_name}} and {{custom.<key>}}.
400 ssrf_blocked A webhook or forwarding URL is not https, or resolves to a private, loopback or link-local address. Use a public https URL.
413 payload_too_large The JSON body is over 100 KB, or an import file is over 5 MB. Send fewer recipients per request, or split the file.
Status code Meaning What to do
401 unauthorized No credential, or an invalid user token. Send X-Api-Key.
401 invalid_api_key The key is malformed, unknown or revoked. Check the value; create a new key if it was revoked.
401 api_key_expired The key’s expiry has passed. Create or rotate a key.
403 missing_permission The key or user lacks a permission the endpoint needs. Add the scope shown in the reference.
403 scope_escalation You tried to give a key scopes your own role doesn’t have. Ask an owner or admin to create it.
403 api_key_not_allowed The endpoint accepts only a signed-in user. Do it in the portal.
403 ip_not_allowed The key’s IP allowlist doesn’t include the caller. Add the address to the key.
403 tenant_suspended The organization is suspended. Contact support.
403 forbidden The action is not allowed for this caller. Check the role or key type.
Status code Meaning What to do
404 not_found The object doesn’t exist in your organization. Objects of other organizations also return this. Check the id and the key’s organization.
409 contact_exists A contact with this number already exists. Update the existing contact (PATCH /v1/contacts/:id).
409 group_exists A contact group with this name exists. Pick another name.
409 template_exists A template with this name exists. Pick another name.
409 pool_exists A device pool with this name exists. Pick another name.
409 already_blacklisted The number is already on the blacklist. Nothing to do.
409 import_already_started POST /v1/contact-imports/:id/start was already called. Poll GET /v1/contact-imports/:id.
409 invalid_campaign_state The campaign’s status doesn’t allow this action (for example, editing a running campaign). Check status first.
409 verification_already_approved The code was already accepted. Treat the number as verified; don’t check again.
409 idempotency_in_progress A request with this Idempotency-Key is still running. Retry shortly with the same key.
422 idempotency_key_reused The key was used with a different request in the last 24 hours. Use a new key.
422 campaign_audience_empty No contact is left in the campaign’s groups or tags. Add contacts, or change the audience.
Status code Meaning What to do
400 file_required No file part in the multipart body. Send the CSV as the file field.
415 unsupported_file_type Not a CSV, a binary file, or not UTF-8. Save as CSV UTF-8 and upload again.
400 csv_empty The file has a header and no rows. Add rows.
400 csv_too_many_rows More than 100,000 rows. Split the file.
400 csv_too_many_columns More than 50 columns. Remove unused columns.
400 csv_cell_too_long A cell has more than 1,000 characters. Shorten it.
400 csv_unterminated_quote A quoted cell never closes. Fix the quoting.
400 csv_duplicate_header Two columns have the same header. Rename one.
Status code Meaning What to do
422 verify_recipient_blacklisted The number is on your blacklist. Remove it from the blacklist if this is a mistake.
403 verify_country_not_allowed Verify isn’t enabled for the number’s country. Allow the country under Settings → Verify.
403 verify_prefix_blocked The number’s range is blocked after unusual traffic. Contact support to review it.
429 verify_resend_limited 3 codes were sent to this number in the last 10 minutes. Wait Retry-After seconds.
429 verify_velocity_exceeded The hourly limit for the country or the organization is reached. Wait Retry-After seconds, or raise the limit in settings.

Your plan sets how many phones, seats, API keys and webhook endpoints you can have, how many messages you can send per day and per month, and which features you can use (Plans). A refused request changes nothing and sends nothing.

Status code Meaning What to do
403 plan_limit_reached The plan has no room for another phone, seat, API key or webhook endpoint, or a send has more recipients than the plan allows per request. Remove one you no longer use, split the send, or ask for a plan change.
403 feature_not_in_plan The plan does not include the feature: pools, scheduled sends or CSV export. Ask for a plan that includes it.
429 quota_exceeded The daily or monthly message allowance is used up. Don’t retry in a loop. Sending works again at params.resetsAt; GET /v1/org/plan shows dayResetsAt and monthResetsAt.

These errors carry params beside the English detail:

code params
plan_limit_reached { plan, resource, limit }. resource is phones, seats, apiKeys, webhooks or recipients.
feature_not_in_plan { plan, feature }. feature is pools, scheduled_sends or csv_export.
quota_exceeded { plan, period, limit, resetsAt }. period is day or month; resetsAt is an ISO 8601 time in UTC.

plan is the plan’s display name. plan_limit_reached and quota_exceeded also carry limit at the top level.

{
"type": "https://docs.smsfabric.com/errors/quota_exceeded",
"title": "Too Many Requests",
"status": 429,
"detail": "The Free plan allows 50 messages a day. The allowance resets at 00:00 UTC.",
"code": "quota_exceeded",
"limit": 50,
"params": { "plan": "Free", "period": "day", "limit": 50, "resetsAt": "2026-11-20T00:00:00.000Z" },
"requestId": "req_w9z2c5f8i1l4o7r0u3x6a9d2"
}
Status code Meaning What to do
429 rate_limited Too many requests. Wait Retry-After seconds. See Rate limits.
429 too_many_listeners Your organization already has 5 listen streams open. Close one, or wait Retry-After seconds for a lost one to free its slot.
500 internal_error Something failed on our side. Retry with backoff; send requestId to support if it persists.
503 unavailable A dependency is down. Retry with backoff.
503 maintenance SMSFabric is in maintenance. Every route answers this, with or without a key. The body has detail (the message), until and retryAfterSeconds. Retry after Retry-After seconds. Queue sends meanwhile.

You will only see these if you call the sign-in endpoints yourself.

Status code Meaning
401 invalid_credentials Email or password is wrong, or the account is locked. The answer is the same in every case.
401 invalid_2fa_code, mfa_token_invalid The 2FA code is wrong, or the sign-in step expired.
401 session_revoked, invalid_token, invalid_refresh_token, refresh_token_reused The session ended. Sign in again.
400 weak_password, breached_password The password is shorter than 12 characters, or appears in a known breach.
409 email_taken, already_member, last_owner Account or team conflicts.
423 account_locked Too many failed attempts. Try again in 15 minutes.