Errors and limits

Everything here applies to every route under https://www.suzko.com/api/v1. Credentials are covered in API credentials.

The envelope

Every response is JSON in one of two shapes.

Success:

{
  "success": true,
  "data": { "object": "message", "id": "msg_Q4f8Zk2LmP7a" },
  "meta": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTEw..." }
}

meta is only there on lists.

Failure:

{
  "success": false,
  "error": "This recipient has opted out of texts from your business.",
  "code": "opted_out",
  "requestId": "req_7Hq2Lm9Xc4Vb8Nz1Kd5Rt3Wy"
}

• Branch on code, never on error. code is stable; error is a human-readable message and can change.
• requestId is req_ plus 24 letters and digits. It's also sent as the X-Request-Id header on every response, successes included. Quote it when you contact support.
• Responses are never cached (Cache-Control: no-store).
• Write requests reject fields the route doesn't know (400 invalid_request) instead of ignoring them, so a typo never silently drops an option.

Status codes

Error codes

Inside a batch, each rejected message carries one of the send codes in its own result instead of failing the whole request. See Send a batch.

Rate limits

Every request that authenticates counts against its credential's budget for its class, even one then refused for a missing scope or plan. A request that's also allowed counts against the whole account's budget (all its credentials together). Windows are fixed one-minute windows.

• A batch counts once, however many messages it holds.
• The account budget is only charged when the credential's budget admits the request, so one runaway credential can't use up its siblings' share.
• Idempotent replays count. Requests refused for a bad credential don't count against either budget; requests refused for a missing scope or plan count against the credential's budget only.
• Over a budget: 429 rate_limited with Retry-After.

Every response that got as far as the rate limiter carries:

Failed authentication has its own limit: 30 failures per minute per IP address (per /64 for IPv6). Past that, failed attempts from that address get 429 rate_limited instead of 401. A valid credential is never refused because of it.

Other limits, separate from the request budgets:

• Texting: the daily cap (daily_limit_reached) and your spend limit apply to every text, however it's sent. Accepted texts go out at the pace carriers allow; see Pacing.
• Webhook test events: 5 a minute per endpoint, 30 an hour per account.
• Request bodies: 5 MB (413). A full 1,000-message batch is far smaller.

Pagination

Lists return an array in data and the next page's cursor in meta.nextCursor. GET /messages and GET /numbers page:

• limit: 25 by default, 100 at most. Anything else is 400 invalid_request.
• cursor: pass meta.nextCursor from the previous page, exactly as you got it. It's opaque; an edited one is 400 invalid_request.
• nextCursor is null on the last page.
• Keep the same filters while you page.

GET /webhooks returns all of the credential's endpoints at once (an account has at most 10), so its nextCursor is always null.

curl "https://www.suzko.com/api/v1/messages?limit=100&cursor=eyJjcmVhdGVkQXQiOiIyMDI2LTEw..." \
  -H "Authorization: Bearer szk_mk_YOUR_MACHINE_KEY"

Data formats

• Timestamps are RFC 3339 in UTC, with milliseconds: 2026-10-20T15:04:05.000Z.

• Money is an exact decimal string plus an ISO 4217 currency, never a float:

  JSONCopy

  { "amount": "50.00", "currency": "USD" }
  

• Phone numbers are E.164: +13175550123.

• Ids are strings with a type prefix, and case-sensitive: messages msg_…, phone numbers pn_…, webhook endpoints wh_…, deliveries whd_…, events evt_…, signing keys whk_…, requests req_…. The API never exposes internal database ids.

• Every resource has an object field naming its type (message, phone_number, usage, webhook_endpoint, webhook_delivery, webhook_secret, event). Event payloads use contact and endpoint_verification too.