Skip to main content

Errors

platform v0.9.11verified 2026-05-14

TelAPI follows a small, predictable error model so your integration can branch on shape rather than free-text.

Envelope​

Errors are JSON bodies with at least:

{
  "error": {
    "code": "STRING_CONSTANT",
    "message": "Human-readable summary.",
    "requestId": "uuid"
  }
}
  • code is a stable identifier you can switch on. New codes are added over releases but existing ones are not silently repurposed.
  • message is for humans. Don't parse it.
  • requestId is the value to send when filing a ticket — it lets the platform operator find the request in SigNoz monitoring quickly.

Detail fields (e.g. field-level validation errors) may appear alongside the standard ones depending on the endpoint. The generated reference will enumerate them per-endpoint; treat unknown extra fields as informational.

Common status codes​

StatusWhen you'll see itRetryable?
400Malformed request — missing required field, invalid shape, unknown endpoint ID.No (fix the request).
401Missing, invalid, or rotated API key — see Authentication.No (fix credentials).
403Key valid but lacks the required scope.No (rebuild key with right scopes).
404Resource doesn't exist or isn't visible to this tenant.No.
409State conflict — e.g. starting a session against an archived flow, or a unique-key collision.Sometimes (after reconciling state).
429Daily / per-minute rate limit hit.Yes, with backoff.
500Internal error — the platform failed in a way it didn't expect. Include the requestId when reporting.Yes, with backoff and idempotency.
502/503/504Transient platform unavailability or upstream gateway issues.Yes, with exponential backoff.

Retry policy you should ship​

For idempotent operations (any GET, plus mints/reads of call tokens):

  • Retry on 429, 500, 502, 503, 504.
  • Exponential backoff with jitter, capped (e.g. start at 250 ms, double, max 8 s, give up after 5 attempts).
  • Surface the final failure to your caller — don't silently swallow.

For state-changing operations:

  • Same retry policy, but ensure the operation is idempotent at your side (use a client-side request ID so duplicate attempts collapse).
  • Do not retry on 400 / 403 / 404 / 409 — these need code or config changes, not more attempts.

Errors that look like API errors but aren't​

SymptomWhere the issue actually is
502 from your own load balancerYour infra in front of TelAPI. Check there first.
401 only from one geographyLikely a key restriction or DNS/proxy oddity at your edge.
Timeouts but TelAPI logs show 200s in SigNozNetwork path between you and TelAPI. The request did succeed; your retry will double-create.

When in doubt, capture the requestId and ask your platform operator to look it up in SigNoz before assuming the API itself failed.

See also​