Errors
Every failure returns the same shape, so one handler covers the whole API. Some errors add a machine-readable code you can branch on.
Error response
{"error": "Monthly minute quota exceeded","code": "QUOTA_EXCEEDED"}
Branch on code, show error
The code is stable and safe to compare against. The error message is written for a developer reading a log and may be reworded, so do not match on its text.
HTTP status codes#
| Status | Meaning | What to do |
|---|---|---|
| 400 | The request was malformed or a field failed validation. | Read the message — it names the field. Do not retry unchanged. |
| 401 | Missing or invalid credentials. | Check the key pair, or that the user session has not expired. |
| 403 | Authenticated, but not allowed. | The account is suspended, or the route needs administrator access. |
| 404 | The resource does not exist, or belongs to another project. | Check the id. Ids are scoped to a project, so another project’s id looks missing. |
| 429 | Rate limited, or the monthly quota is used up. | See the code. Back off, or upgrade the plan. |
| 500 | Something failed on our side. | Retry with backoff. If it persists, send us the time and your App ID. |
| 501 | The feature is not available on this platform. | Currently only cloud recording. |
| 503 | The feature is not configured yet. | Billing returns this while payments are not enabled. |
Error codes#
| Code | Status | Cause | Fix |
|---|---|---|---|
QUOTA_EXCEEDED | 429 | The account has used its monthly participant-minutes. | New tokens are refused; calls already running continue. Upgrade the plan, or wait for the monthly reset. See Usage and quotas. |
ACCOUNT_SUSPENDED | 403 | The account has been suspended. | No tokens are issued. Contact support. |
RECORDING_NOT_AVAILABLE | 501 | Cloud recording is not offered — no customer media is stored. | Record in your own infrastructure, or ask us about a customer-owned bucket. |
Messages you are most likely to see#
| Message | Status | What went wrong |
|---|---|---|
| AppLooma API Key and Secret are required in headers | 401 | You sent neither x-applooma-key nor x-applooma-secret. |
| Invalid or inactive API Key/Secret | 401 | The pair does not match, or the key has been disabled in the console. |
| Authentication token required | 401 | A dashboard endpoint was called without a bearer token. |
| Invalid or expired token | 401 | The session token has expired. Sign in again. |
roomName must match [a-zA-Z0-9_-]{1,64} | 400 | The channel name contains a character that is not allowed, or is empty or too long. |
| identity is required (1-128 chars) | 400 | The participant identity was missing, empty or too long. |
role must be one of 'host' | 'cohost' | 'audience' | 400 | An unknown role was requested. |
| metadata must be an object | 400 | Metadata was sent as a string or an array. It must be a JSON object. |
| metadata must be under 2048 bytes | 400 | Metadata is embedded in the token and broadcast to every participant, so it is capped. |
| Too many token requests, please try again later. | 429 | More than 600 token requests in a minute for one API key. See Limits. |
| Too many requests, please try again later. | 429 | More than 1200 requests in a minute for one API key on the SDK endpoints. |
| Gift not found | 404 | The gift id does not exist in this project, or is inactive. |
| urls must be 1-3 rtmp(s):// destinations | 400 | A media push needs between one and three RTMP destinations. |
| Push not found or already stopped | 404 | The push id is unknown, already finished, or belongs to another project. |
Failures inside the SDKs#
These never reach the API — they happen in the client, and the API cannot report them.
| Symptom | Cause | Fix |
|---|---|---|
| Join succeeds but nobody sees your video | The token was issued with role audience, which cannot publish. | Issue a token with host or cohost and rejoin. |
| Your own connection drops when a second device joins | Both used the same identity. An identity is one participant. | Give every participant a unique identity. |
| No camera or microphone | Permission was denied, or on Android was never requested at runtime. | Request permissions before joining and handle the refusal. |
| Remote audio is silent in a browser | Autoplay was blocked because no user gesture had occurred. | Attach media in a click handler, or show an unmute button. |
| Video tile stays black | The user was rendered before their camera track arrived. | Render on the track-subscribed event, not only on user-joined. |
| Already in a channel | joinChannel was called twice on one engine. | Call leaveChannel first, or create a second engine. |
Reporting a problem#
Send us these and we can usually find the session:
- Your App ID
- The channel name and the participant identity
- Roughly when it happened, with a time zone
- The full error response, including the
code