Errors and Testing

If you only test the happy path, telephony will punish you.

Common error families

Expect these kinds of failures:

• invalid or revoked API key
• validation errors on line or call creation
• insufficient credits
• consent missing for outbound calls
• webhook destination failures
• missing resources
• rate limiting

Error response shape

Every error response follows the same envelope. The code field is the stable, machine-readable identifier you should branch on. The message field is human-readable and may change over time.

1
{
2
  "error": {
3
    "code": "validation_error",
4
    "message": "Request validation failed.",
5
    "details": [
6
      {
7
        "field": "name",
8
        "message": "Required"
9
      }
10
    ]
11
  }
12
}

Error codes

Every error response includes a stable code field. Branch on the code, not the message.

Error response examples

Concrete shapes for the codes you are most likely to hit in production.

1
{
2
  "error": {
3
    "code": "insufficient_credits",
4
    "message": "Insufficient balance to place call."
5
  }
6
}

1
{
2
  "error": {
3
    "code": "payment_method_required",
4
    "message": "Add a payment method to provision additional numbers."
5
  }
6
}

1
{
2
  "error": {
3
    "code": "consent_required",
4
    "message": "Outbound calls require consent for this destination."
5
  }
6
}

1
{
2
  "error": {
3
    "code": "conversation_window_expired",
4
    "message": "Outbound SMS requires either an inbound message from this number within the last 24 hours, or an active explicit_outbound consent record on file for this (line, recipient) pair (record one via POST /v1/consent)."
5
  }
6
}

1
{
2
  "error": {
3
    "code": "call_in_progress",
4
    "message": "Line already has an active call."
5
  }
6
}

1
{
2
  "error": {
3
    "code": "rate_limited",
4
    "message": "Too many requests. Retry after the window resets."
5
  }
6
}

Rate limits

Rate limits vary per endpoint. Most use a 1 hour rolling window; SMS is the only endpoint with a 1 minute window.

When you exceed a limit, the API returns 429 Too Many Requests with the rate_limited error code.

SDK error handling

Both SDKs surface a typed error class so you can branch on code without parsing response bodies.

1
import { Saperly, SaperlyError } from '@saperly/sdk';
2
3
try {
4
  const call = await saperly.calls.create({ lineId: 'LINE_ID', toNumber: '+1...' });
5
} catch (err) {
6
  if (err instanceof SaperlyError) {
7
    console.error(err.code, err.message); // e.g. "insufficient_credits"
8
  }
9
}

What to test before shipping

Inbound call

• call connects
• caller hears the expected first response
• transcript is readable
• call record is queryable after completion

Outbound call

• blocked without consent
• succeeds with consent
• failure state is visible if destination is unreachable

SMS

• inbound event arrives
• reply succeeds
• conversation history looks correct

Webhooks

• your endpoint is idempotent (Saperly delivers each webhook once; network-level duplicates are still possible)
• non-200 responses are visible in webhook delivery logs
• test endpoint can hit your webhook before production traffic does

Load testing

Recommended approach:

1. Create 2-3 test lines
2. Simulate inbound webhook events against your handler
3. Place outbound calls to your own test numbers
4. Monitor webhook delivery success rate and latency
5. Check billing transactions to verify correct charging

Useful debugging endpoints

• GET /api/v1/webhooks/deliveries
• GET /api/v1/webhooks/stats
• POST /api/v1/webhooks/test
• GET /api/v1/calls
• GET /api/v1/compliance/audit

Advice

Break your webhook on purpose once in staging.

Then look at delivery logs and the failure-mode user experience. Better to learn that path deliberately than from your first customer.