Errors and response behavior
Local JSON error envelope
Errors created by the Music API use:
{"error":{"message":"Human-readable explanation"}}The message can be English or Swahili depending on the route and failure path. The status code is the important machine-readable signal. Do not branch on message text.
| Status | Common local meaning |
|---|---|
400 | Malformed JSON or invalid required input |
401 | No valid session / Ngamia reports unauthorized |
403 | Origin not on allowlist |
404 | Proxy path is outside /v1/ |
502 | Upstream unavailable, generation timeout, or invalid provider response |
| Upstream status | Model request error or proxy result where applicable |
Nest’s Express JSON and URL-encoded parsers accept bodies up to 2 MB. Requests above the parser limit or malformed JSON can be rejected by Express before the controller runs; those parser errors do not necessarily use the Music API’s {error:{message}} envelope.
Responses are not all JSON
GET /api/auth/session returns the upstream /v1/me body and content type when successful. When unauthenticated it returns { "authenticated": false } with status 200; an upstream 404 is translated to { "authenticated": true } with status 200. This lets the web app decide whether a profile is available while treating a valid session with no profile endpoint result as authenticated.
GET /api/music/models returns the upstream response text with its status and content type. POST /api/music/generate returns successful audio bytes, usually audio/mpeg; errors are JSON. The generic proxy streams the upstream body and preserves selected headers rather than wrapping the result in a JSON envelope.
Upstream status handling
Models preserve the upstream status. Generation turns non-2xx upstream responses into the local JSON error envelope, extracting error.message or message when the body parses as JSON and otherwise using a generic message. The status remains the upstream status. The generic proxy preserves the upstream status and body. For all three, network/timeout outcomes depend on route-specific handling.
Timeouts and safe retries
Generation and authenticated proxy requests allow up to 280 seconds for their upstream fetch. The NestJS service does not set a platform-specific request-duration limit; configure the host to allow enough time. A generation timeout is returned as 502; the API explicitly advises checking activity before retrying to reduce accidental duplicate charges. Use an Idempotency-Key UUID for a generation attempt when supported by the Ngamia API. Keep the same key for a retry of that logical attempt; create a new key for a new intentional generation. The proxy forwards this header.