Skip to main content

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 with lqr_.
  • 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 /v1 appears twice, the app adds it itself: use https://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.

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.