Skip to Content
LYNKORIADocs

Errors

Error codes returned by the API and SDKs, what causes them, and how to handle each one.

Every failure has the same shape, over REST and socket acknowledgements alike:

{ "error": { "code": "rate_limited", "message": "Too many requests", "requestId": "…" } }

The SDKs throw LynkoriaError with code, status (HTTP status, 0 for network and socket errors), message, requestId and optional details.

import { LynkoriaError } from '@lynkoria/client';

try {
  await client.messages.send({ conversationId, text, clientMessageId });
} catch (err) {
  if (err instanceof LynkoriaError && err.code === 'rate_limited') {
    // back off, then retry with the SAME clientMessageId
  } else throw err;
}

Codes

CodeHTTPMeaningWhat to do
bad_request400The request is malformed or breaks a rule, such as an invalid ID or a role on a group call.Fix the request; details lists invalid fields.
unauthorized401Missing, invalid, expired or revoked credential.Backend: check the key and its mode. Client: the SDK refreshes the token once automatically.
forbidden403The credential is valid but lacks a scope, or a policy forbids the action.Add the scope to the key, or change the messaging policy.
not_found404The resource does not exist or belongs to another project or tenant.Check IDs; use the Lynkoria UUID, not your product ID.
conflict409The resource is in a conflicting state, for example a product ID reused by another tenant.Use a different product ID or resolve the state.
payload_too_large413Message or attachment exceeds the limit.Reduce the size, or raise the policy limit.
rate_limited429Too many requests in the current window.Back off with jitter and retry.
quota_exceeded429An environment quota was hit: room size, concurrent rooms or tokens per minute.Wait, end idle calls, or raise the quota in the console.
feature_disabled403The feature is off for this environment.Enable it on the console’s Environments tab.
internal_error500Unexpected server error.Retry idempotent operations; report the requestId if it persists.
service_unavailable503A dependency is unavailable, or a network error occurred in the SDK.Retry with backoff.

Retrying safely

  • Creating calls and conversations, and sending messages, are idempotent on your product IDs and clientMessageId. Retry them with the same IDs.
  • The client SDK already retries socket connections with exponential backoff and jitter, refreshes tokens, and resyncs history. It does not queue sends while offline: show the failure and let the user retry.
  • Media errors from the browser (NotAllowedError, NotFoundError) are not LynkoriaErrors; handle them as device problems.

On this page