Problem details, every time.
Every error is an RFC 9457 problem with a stable code, the HTTP status, a readable detail and the request ID. Validation errors list the exact path of each invalid field.
Shape
Problems use application/problem+json. The type URL points to the code's anchor on this page. Branch on code, never on detail, which is written for people and may change.
{
"type": "https://www.medera.info/developers/errors#payload_too_large",
"title": "Payload too large",
"status": 413,
"code": "payload_too_large",
"detail": "More than 3600 frames for sandbox mode; send at a lower frame rate.",
"request_id": "req_…"
}400invalid_json
Invalid JSON
The request body is not valid JSON.
What to do. Check the body is valid JSON and the Content-Type is application/json.
400invalid_request
Invalid request
The request is malformed, for example a multipart body without the required part.
What to do. Check the multipart parts: audio must be a file part, other parts JSON text.
404not_found
Not found
The resource does not exist.
What to do. Check the path and the version prefix /v1, or the biomarker key against the catalog.
405method_not_allowed
Method not allowed
The endpoint does not support this HTTP method.
What to do. Use the method in the Allow header: POST for analyze endpoints, GET for the catalog.
413payload_too_large
Payload too large
The body, the audio or a series exceeds the limit for your mode.
What to do. Send less: shorter audio, fewer frames or beats, or split the request. Live limits are higher than the sandbox's.
415unsupported_media_type
Unsupported media type
The Content-Type is not accepted by this endpoint.
What to do. Use multipart/form-data or audio/wav for audio, application/json for everything else.
422validation_failed
Validation failed
The body is well formed but a field is missing or out of range; see errors[].
What to do. Read errors[]: each entry names the exact field path and what is wrong with it.
422invalid_audio
Invalid audio
The audio is not a decodable PCM or IEEE-float WAV file.
What to do. Send a PCM (8, 16, 24 or 32-bit) or IEEE-float (32 or 64-bit) WAV, 8 to 192 kHz, 1 to 8 channels.
429rate_limited
Too many requests
The per-minute limit for your key (live) or address (sandbox) was reached; see Retry-After.
What to do. Wait for Retry-After seconds. Sandbox limits are per address; live limits per key.
500internal_error
Internal error
Something failed on our side. Quote the request ID if you contact us.
What to do. Retry once. If it persists, contact us with the request ID; we can trace it without seeing your data.
Still stuck? Contact us with the request ID.