Errors

Every senderZ API response follows a consistent envelope format. Understanding this format makes error handling predictable across all endpoints.

Response Envelope

All API responses use this JSON structure:

{
  "data": {},
  "error": "Human-readable error message",
  "code": "MACHINE_READABLE_ERROR_CODE"
}

On success, error and code are absent. On error, data is absent.

Success Example

{
  "data": {
    "message_id": "01JMSG123ABC",
    "status": "queued"
  }
}

Error Example

{
  "error": "The recipient has opted out of messages from your account.",
  "code": "RECIPIENT_OPTED_OUT"
}

HTTP Status Codes

senderZ uses standard HTTP status codes. Here is what each one means in context:

Success Codes

Client Error Codes

Server Error Codes

Typed Error Codes

Every error response includes a code field with a stable string identifier. These codes never change between API versions, making them safe to match against in your code.

Authentication Errors

Validation Errors

Messaging Errors

Quota Errors

Resource Errors

Detection Errors

Handling Errors in Code

Use the code field for reliable error handling — never match against the human-readable error string, which may change.

const res = await fetch('https://api.senderz.com/v1/messages', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sz_live_YOUR_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: '+15551234567',
    channel: 'auto',
    body: 'Hello!',
  }),
})

const result = await res.json()

if (!res.ok) {
  switch (result.code) {
    case 'RECIPIENT_OPTED_OUT':
      // Remove this number from your send list
      break
    case 'TRIAL_EXPIRED':
      // Redirect user to subscribe
      break
    case 'RATE_LIMIT_EXCEEDED':
      // Wait and retry
      const retryAfter = res.headers.get('Retry-After')
      break
    case 'NEW_CONTACT_LIMIT':
      // Queue for tomorrow or upgrade plan
      break
    default:
      console.error(`API error: ${result.code} — ${result.error}`)
  }
}

Retry Strategy

Not all errors should be retried. Here is a quick guide:

Frequently Asked Questions

What does TRIAL_EXPIRED mean? Your 14-day free trial has ended and you have not subscribed to a plan. All API requests will return this error until you choose a plan (Starter, Growth, or Scale) from the developer portal.

Why do I get RECIPIENT_OPTED_OUT when I know the number is valid? The recipient has previously sent a STOP keyword to your tenant’s phone number. senderZ automatically blocks all future messages to opted-out numbers. The recipient must send START to re-subscribe.

How do I know which field caused a VALIDATION_ERROR? The error field in the response describes exactly which field is invalid and why. For example: “The ‘to’ field must be a valid E.164 phone number starting with +”.

What is the difference between QUOTA_EXCEEDED and NEW_CONTACT_LIMIT? QUOTA_EXCEEDED means you hit your monthly API call ceiling. NEW_CONTACT_LIMIT means you reached your daily limit for messaging phone numbers you have never contacted before. Messages to existing contacts are always unlimited.

Can I get more details about a DELIVERY_FAILED error? Yes. Use GET /v1/messages/:id to retrieve the full message record, which includes a failure_reason field with carrier-level error details when available.