Troubleshooting
Find the symptom, then the fix. Every error also has a code with its own entry in Errors.
Keys and sign-in
My app or script says 401
Check the key on your account page, then the header. It must be exactly Authorization: Bearer lqr_...: the word Bearer, one space, then the whole key. The error message says which part is wrong.
- The key starts with
sk-. That is an OpenAI key. Make a Loquela Remote key on your account page; ours start withlqr_. - The key was copied from a password manager or chat. Copies can lose the last characters or pick up a space or line break. Copy it again, or make a new key.
- It worked yesterday. The key may have been revoked on the account page. Make a new one.
- Quick check:
curl https://api.getloquela.com/v1/models -H "Authorization: Bearer $LOQUELA_API_KEY"answers 200 for a valid key.
Every request is refused with too_many_failed_attempts
Something sent 20 requests with a bad key from your address within 10 minutes, so the API and MCP are closed to that address for 15 minutes. Usually a script retries with a wrong key. Stop it, fix the key, then wait for the time in the message.
"Use https://api.getloquela.com"
The request went to http://. Change the address to https://. If it carried a key, that key travelled unencrypted: revoke it and make a new one.
Addresses
404 with unknown_endpoint
- Base URL. Most OpenAI-compatible apps and SDKs want
https://api.getloquela.com/v1. If the error says/v1appears twice, the app adds it itself: usehttps://api.getloquela.com. - Chat, translation, text to speech or realtime. Loquela Remote turns speech into text. Apps that need a chat model or live transcription cannot use it.
I opened the address in my browser and got a page
That is expected. The API and MCP addresses are for apps and assistants; in a browser they show a page explaining how to use them.
Sending audio
invalid_upload: the form is not right
Send multipart/form-data with the audio in a field named file:
curl https://api.getloquela.com/v1/audio/transcriptions \
-H "Authorization: Bearer $LOQUELA_API_KEY" \
-F file=@meeting.m4a
The @ matters: without it, curl sends the file's name as text. Do not set Content-Type yourself; curl and HTTP libraries add the boundary the server needs. In Python with requests, pass files={"file": open("meeting.m4a", "rb")}, not data= or json=.
The file is over 100 MB, or I got an HTML 413 page
Convert it to a compressed format first. About 3 hours of speech fits as a 64 kbps MP3 or Opus file:
ffmpeg -i recording.wav -ac 1 -c:a libopus -b:a 64k recording.ogg
An upload right at 100 MB can be refused by the network in front of the service with an HTML page instead of our JSON error. The same fix applies.
"This is a web page (HTML), not an audio file"
The link or file is a web page. Share links from Google Drive, OneDrive, iCloud and similar open a page about the file, not the file. Download the file and send it; an assistant can use create_upload_link. For Dropbox, change dl=0 to dl=1 at the end of the link.
The file looks cut off, ends early, or has no audio
- Cut off: an MP4 or M4A whose recording did not finish saving cannot be read. If the recording app has a recovery option, use it; otherwise re-record.
- Ends early: the copy or upload stopped partway. Check it plays to the end in a media player, then send it again.
- No audio: a video without a sound track, or a microphone that recorded nothing.
The type is not supported, but the file name says .mp3
We read the type from the file's contents, not its name. A renamed file is still its original type. Convert it with a converter or ffmpeg instead.
The transcript is empty
The audio may be silent, very quiet, or not speech (music, noise). Play it back to check. Audio in another language sent as English comes back poorly or empty: send its language, or auto, when other languages are on for your account.
The transcript says "partial"
"partial": true in JSON (or the x-loquela-partial: true header) means part of the audio could not be transcribed, and you are charged only for the part that was. Try the request again; if the same part fails each time, that part of the file may be damaged.
Speaker labels are missing
With speakers or diarize on, a file where labels could not be made still returns its full transcript, marked "speaker_labels": "unavailable" in JSON answers (MCP text results say so in a note). If you get speaker_labels_not_offered, labels are switched off for the moment; send the request without them.
Audio is refused with unsupported_language
The app sent a language that is not on for your account. Switch other languages on from Languages on your account page, or set the app's spoken language to English for this provider, or leave the language out.
Long files
My long request stopped with a 524 page
text, srt and vtt answers on long files can be cut off by the network after about two minutes of waiting. Ask for verbose_json instead, which keeps the connection open, and build text or subtitles from its segments.
A long request returned 200 but the body is an error
Long JSON requests start with 200 and keep the connection open while they work. If they then fail, the error arrives in the body. Check the body for error on long files. You are not charged for a failed request.
Minutes and limits
insufficient_quota but I just bought minutes
Check your balance with GET /v1/usage or on the account page. A purchase shows there once the payment completes; if it is not there after a few minutes, email us. If the audio is longer than the minutes left, the request is refused whole: buy more, or send a shorter file.
key_limit_reached
This key has a monthly minute limit, set on your account page. Raise or remove it there, or use another key. Limits reset on the 1st of each month (UTC).
concurrency_limit or rate_limit_exceeded
Your plan runs a set number of requests at a time and in a minute (see limits). Send fewer in parallel, wait for Retry-After before retrying, and add a growing delay between retries in loops.
503 server_busy or service_unavailable
The service is busy, starting up, paused for maintenance or briefly unreachable. Wait for Retry-After and try again. The status page shows whether something is wrong.
AI assistants (MCP)
Claude or ChatGPT will not connect
- Address. It must be exactly
https://api.getloquela.com/mcp. - ChatGPT. Custom connectors need developer mode turned on for connectors.
- The approval page warns you. It warns when an app's name does not match where it would send you after approving. If you did not expect that, choose Deny.
- It asks you to sign in again. The connection expired or was disconnected on your account page. Connect again.
Claude Code, Cursor or VS Code says 401
These clients send an API key in a header. Check the header is Authorization: Bearer lqr_... with a current key; see My app or script says 401.
transcribe_url cannot download the file
The link must be a public https:// link to the file itself, which anyone can download without signing in. Links to private files, sign-in pages or local network addresses do not work. For a file on your computer or behind a sign-in, use create_upload_link.
transcribe_upload says nothing has been uploaded, or the link expired
Upload the file to the link first (curl -T "<file>" "<upload_url>", or open the link in a browser), then call transcribe_upload. Links last 15 minutes and take one file; after that, create a new one.
transcribe_audio refuses the clip
It takes base64 clips up to 8 MB. For larger files, use create_upload_link. The string must be the file's bytes in standard base64; a data:audio/...;base64, prefix is accepted.
Still stuck
Email info@getloquela.com with the error message and its request id (in the message for errors on our side, and always in the x-request-id header). The request id is all we can look up, since nothing about your audio is kept.