TelDev

Errors

TelDev fail-closed /v1 responses return a JSON error object with a stable code.

All errors are JSON:

{
  "error": {
    "code": "campaign_not_approved",
    "message": "Campaign cmp_12 is not approved for tmobile."
  }
}

| Status | Code | When |

| --- | --- | --- |

| 400 | idempotency_key_required | Live key POST without Idempotency-Key |

| 400 | invalid_request | Missing from / to / body, invalid JSON, or at in the past / unparseable |

| 401 | unauthorized | Missing/invalid Bearer, or key not nl_test_ / nl_live_ / trl_ |

| 402 | trial_exhausted | No remaining trial seconds and no paid plan (never granted, or not yet landed on Personal). Device-first: Trial's one-time 10 minutes are gone |

| 402 | plan_exhausted | Free or Personal minute cap is gone |

| 402 | included_exhausted | A published included pack (Personal 175) is empty. /v1 will not place the next live call |

| 422 | device_only_plan | Trial / Free / Personal to is E.164 and there is no bridge flag |

| 422 | unverified_destination | Personal cell bridge to is not a number they verified with a one-time code |

| 403 | trial_forbidden | Trial token used on number buy or SMS |

| 404 | not_found | Unknown id, or Twilio aliases disabled |

| 409 | idempotency_conflict | Same Idempotency-Key, different body |

| 422 | campaign_not_approved | Fail closed: campaign missing, unknown, not approved for the destination MNO, or the carrier rejected 10DLC |

| 422 | number_not_owned | from is not an account number |

| 422 | agent_not_found | Unknown agent id |

| 422 | no_route | Carrier has no inventory/route, or Route failover bandwidth has no client |

| 504 | carrier_timeout | Carrier HTTP timeout or 5xx |

Idempotency

  • Same key + same body → original response replayed.
  • Same key + different body → 409.
  • Live keys must send Idempotency-Key on every POST.
  • Test keys may omit it.