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
| Code | HTTP | Meaning | What to do |
|---|---|---|---|
bad_request | 400 | The 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. |
unauthorized | 401 | Missing, invalid, expired or revoked credential. | Backend: check the key and its mode. Client: the SDK refreshes the token once automatically. |
forbidden | 403 | The 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_found | 404 | The resource does not exist or belongs to another project or tenant. | Check IDs; use the Lynkoria UUID, not your product ID. |
conflict | 409 | The 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_large | 413 | Message or attachment exceeds the limit. | Reduce the size, or raise the policy limit. |
rate_limited | 429 | Too many requests in the current window. | Back off with jitter and retry. |
quota_exceeded | 429 | An environment quota was hit: room size, concurrent rooms or tokens per minute. | Wait, end idle calls, or raise the quota in the console. |
feature_disabled | 403 | The feature is off for this environment. | Enable it on the console’s Environments tab. |
internal_error | 500 | Unexpected server error. | Retry idempotent operations; report the requestId if it persists. |
service_unavailable | 503 | A 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 notLynkoriaErrors; handle them as device problems.