Errors

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.

413 problem
{
  "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.

401unauthorized

Unauthorized

The Authorization header is missing, malformed or carries an unknown key.

What to do. Send Authorization: Bearer with the sandbox key or your live key. A live key that was rotated no longer works.

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.