Errors

Every error below is the literal response shape a given failure produces — not a paraphrase. Where a field is named error versus code, that's the real, if occasionally inconsistent, field name in that response.

Authentication

HTTP	Code	Why	Fix
401	`auth_invalid_key`	The API key is missing, misspelled, or has been revoked.	Check the `Authorization: Bearer …` header is present and use an active key from API Keys.

JSON

{ "error": "Invalid or inactive API key.", "code": "auth_invalid_key" }

Validation (400)

Malformed input fails with DRF's standard per-field shape — a dictionary keyed by the field name, valued with a list of messages for that field:

JSON

// to: "0000" 
{ "to": ["'0000' is not a valid E.164 number. Expected format: +212612345678"] }

More than one field can fail at once; each appears as its own key in the same object.

Quota and plan limits

HTTP	Where	Why	Fix
402	Sending	Monthly SMS quota used up for your plan.	Wait for the next billing period, or upgrade your plan.
402	Pairing a SIM	Your plan's device limit is already in use.	Remove an existing SIM, or upgrade. See SIM Cards.

JSON

// 402 — sending past your SMS quota
{
  "error": "quota_exceeded",
  "code": "monthly_limit_reached",
  "detail": "You have used 300 of 300 messages this month. Upgrade your plan to continue sending."
}

JSON

// 402 — pairing past your device limit
{
  "error": "device_limit_reached",
  "detail": "Device limit reached for your plan (1/1). Upgrade at connecfy.com to add more devices."
}

Sender number routing

HTTP	Code	Why	Fix
403	`from_number_not_found`	The `from` number isn't attached to any SIM on your account.	Use a number that belongs to one of your SIMs, or check for a typo.
403	`from_number_access_denied`	The number exists, but this account has no rights to send from it.	Ask an admin to grant access, or use a number you own outright.
503	`device_inactive`	The SIM behind that number has been deactivated.	Register a replacement SIM, or contact your admin.

Not found

HTTP	Code	Why
404	`not_found`	No message with that id exists on your account — this includes ids that exist on someone else's account, so it can't be used to enumerate other accounts' messages.

Rate limiting (429)

JSON

// 429, header: Retry-After: 14
{ "detail": "Request was throttled. Expected available in 14 seconds." }

Full numbers per endpoint in Rate Limits.