Error Codes

This page lists the errors you can run into when calling the Cochl.Sense Cloud API — both errors returned immediately when a request is rejected, and errors that show up later inside a completed analysis job. If you’re using the official Python library (cochl), see §6 for how these appear as exceptions.

1. Two places errors come from

The most important thing to understand about this API’s errors is when they happen:

Response body shapes

The shape of the error body depends on which kind of error it is — worth knowing before you write a parser:

2. Authentication keys

A project key doesn’t expire on its own — issuing a new one just invalidates the old one, and a request made with an invalidated key gets Invalid API key. Key validation results are cached for up to 10 minutes, so a key change can take up to 10 minutes to take effect.

3. Request errors (synchronous — Project Key)

These are HTTP errors returned by POST /api/v1/analyze and POST /api/v1/analyze_file at the moment the request is accepted or rejected.

On success, both endpoints return 200 with {"job_id": "...", "status": "accepted", "created_at": "..."}. Analysis then continues in the background — see §4.

4. Service errors inside job results (asynchronous)

Because analyze / analyze_file return 200 accepted as soon as the request is queued, problems in the analysis engines (ASR, Sound Event Detection, Caption) aren’t HTTP errors — they appear inside the job result once you fetch it. GET /api/v1/jobs/{job_id} returns HTTP 200 even when a service failed; only that service’s entry is marked status: "error" (other services that succeeded still return their results — partial success is normal).

GET /api/v1/jobs/{job_id}  ->  HTTP 200
{
  "job_id": "b8cbefce-...",
  "status": "completed",
  "result": {
    "sound_event_detection": { "status": "error", "error": "max_workers must be greater than 0" },
    "speech_analysis":        { "status": "error", "error": "ASR Engine API error: 500" },
    "caption":                { "status": "error", "error": "Caption API error: 500" }
  }
}

Always check each service’s status field — a completed job is not the same as a fully successful one.

5. Speaker Recognition errors (Organization Key — /api/v2)

The Speaker Recognition API (used by SpeakerProfileApi) always wraps its response in a {data, error, debug} envelope. Authentication failures return 401; everything else — business-rule violations — return HTTP 200 with an error field (kept for compatibility with the legacy SR server).

Voice files are limited to 10 MB and 10 minutes each (the library blocks oversized files before sending; the server separately enforces a 100 MB hard cap). Each speaker supports up to 20 voice samples (5–20 recommended for accuracy — no confirmed error message exists yet for exceeding this). An organization can register up to 50 speakers in total.

6. Errors in the Python library (cochl 2.0.1)

Most users call this API through the official Python library rather than raw HTTP. The exceptions it actually raises can differ from the raw API response above, so they’re listed separately.

6.1 IntegratedApi (audio analysis — Project Key)

When a request fails (any non-2xx response), the library discards the server’s detailed message and uses only the HTTP reason phrase as the exception message. For example, the server’s Invalid API key becomes just Unauthorized. Every such exception is a CochlSenseException, and its message always has "Please contact support@cochl.ai" appended.

6.2 SpeakerProfileApi (speaker registration & recognition — Organization Key)

Because Speaker Recognition’s business-rule violations come back as 200 + error, the library passes the server’s actual message straight through. Authentication failures (401) are the one exception — those still collapse to the reason phrase, same as IntegratedApi.

6.3 Recommended error-handling pattern

from cochl.sense import IntegratedApi, IntegratedApiOptions
from cochl.sense.exception import CochlSenseException
from cochl.sense.http_request import HttpRequestException
import urllib.error

api = IntegratedApi("YOUR_PROJECT_KEY")

try:
    job = api.analyze_file(
        "audio.wav",
        IntegratedApiOptions(sound_event_detection=True),
    )
    result = api.get_completed_result(job["job_id"])

    if result is None:
        # Analysis failed, or the stream timed out — not an exception
        print("analysis did not complete")
    else:
        sed = result.get("sound_event_detection", {})
        if sed.get("status") != "success":
            print("SED failed:", sed.get("error"))

except CochlSenseException as e:        # inherits BaseException — must be explicit
    print("API error:", e.message)      # e.g. Unauthorized / Bad Request / Internal Server Error
except HttpRequestException as e:       # empty file / connection failure
    print("request error:", e.message)
except FileNotFoundError as e:          # missing file
    print("file not found:", e)
except urllib.error.HTTPError as e:     # unknown job_id in get_completed_result
    print("job not found:", e.code)

Even if you keep a catch-all except Exception: as a safety net, put except CochlSenseException: before it — otherwise API errors go uncaught and the program exits.

6.4 Legacy Client (EventDetectionApi, v1.x)

7. Rate limits & audio length

There is currently no request-rate limit — sending requests in a burst won’t get you a 429. Under heavy load, requests may instead hit downstream timeouts (ASR: 30s, Caption: 120s) and surface as a service error in the job result (§4).

The API and the Python library have no server-side audio length limit. The 1-hour cap only applies to the web Dashboard. A very long file sent via the API can still fail — not from a length check, but from processing taking long enough to hit the downstream timeouts above.

See also

• Custom Sound: Speaker Profile—registering and recognizing speakers; see §5 above for its error cases
• Getting Started—setup and your first request
• Sound Event Detection—detection details and service options referenced in §3