Errors

Error response shape, public error_code values, and debugging tips.

MusiMap uses two error response families on https://api.musimap.com, depending on which surface you call. Branch on the HTTP status code and the machine-readable error field in each family. Do not parse human-readable message or error_description text in application logic.

Two response regimes

  • /oauth/*. OAuth/OIDC-native errors (RFC 6749 §5.2). Fields: error, optional error_description. No MusiMap envelope.
  • /v1/*. MusiMap envelope errors: {status, message, data} with data.error_code.

Meta and discovery endpoints (/status, /versions) are not business API calls and do not use these error envelopes for normal success responses. See Status & versioning.

OAuth/OIDC error shape

Applies to OAuth 2.0 and OpenID Connect protocol endpoints such as POST /oauth/token, POST /oauth/revoke, and GET /oauth/userinfo. 

{
  "error": "invalid_token",
  "error_description": "The access token is missing, expired, or invalid."
}

Common OAuth error values include invalid_request, invalid_client, invalid_grant, invalid_scope, invalid_token, and insufficient_scope. See the Authentication guide for token-exchange errors.

/v1/* MusiMap error envelope

Business API endpoints under /v1/* return errors inside the standard MusiMap envelope. The HTTP status code matches the top-level status field. 

{
  "status": 401,
  "message": "Invalid or missing bearer token.",
  "data": {
    "error_code": "invalid_token"
  }
}

Client rules:

  • Branch on HTTP status + data.error_code.
  • Treat message as human-readable diagnostic text only.
  • data.details is optional; its shape depends on the endpoint (string or structured entries).
  • request_id is not included in error responses today. Do not depend on it in client logic.

Validation error example

When create validation fails on a public field such as mode, POST /v1/ingestions returns HTTP 400 with a string data.details message: 

{
  "status": 400,
  "message": "Bad request",
  "data": {
    "error_code": "validation_error",
    "details": "Unsupported ingestion mode: 'ftp'. Supported values: api_json, s3_csv, s3_ddex, s3_scan."
  }
}

Public error_code reference

The table below is the canonical public registry for /v1/* responses. Codes marked implemented are returned by the gateway today. Codes marked reserved are part of the public contract for upcoming business endpoints and should be handled defensively in client code.

HTTP error_code Meaning Typical fix
400 invalid_request The request body or parameters are malformed or incomplete. Check JSON syntax, required fields, and query parameters.
401 invalid_token The bearer token is missing, expired, malformed, or no longer active. Request a new access token from POST /oauth/token.
403 insufficient_scope The token is valid but does not include the scope required by this endpoint. The envelope may include data.missing_scopes. Request a token with the correct scope. See References → Scopes.
401 invalid_token_context The bearer token is syntactically valid but its organisation or client context cannot be resolved. Re-issue the token. Confirm the OAuth client is active and still belongs to the organisation.
403 entitlement_required Your organisation does not hold the commercial entitlement for this capability. Ask MusiMap to enable the product entitlement, then delegate the matching scopes.
403 entitlement_revoked The entitlement that backed this scope was removed after the token was issued. Request a new token after the entitlement is restored and scopes are re-delegated.
403 catalogue_forbidden The requested catalogue is outside this client's binding or organisation access. Use GET /v1/catalogs and respect catalogue binding rules.
403 resource_forbidden The caller is authenticated but not allowed to access this resource. Verify organisation ownership and catalogue context.
404 not_found The resource does not exist or is outside your access scope. Verify the resource id and catalogue context.
422 missing_catalogue_context The operation needs a customer catalogue and none could be resolved. Pass catalog_id, bind the OAuth client to a catalogue, or ensure an organisation default exists.
422 validation_error The request is syntactically valid but semantically invalid. Fix the fields listed in data.details.
429 rate_limited Too many requests in a short period. Back off and retry later. Cache access tokens.
429 quota_exceeded Your plan or credit limit has been reached. Check usage in the dashboard or contact support.
503 upstream_unavailable MusiMap could not validate or process the request because a dependency is unavailable. Retry later. Check GET /status for coarse availability.

Debugging checklist

  • Confirm Authorization: Bearer <token> is present on every /v1/* call.
  • Call GET /v1/me to verify token context (principal, organisation, catalog, scopes).
  • Compare OAuth errors on /oauth/* with MusiMap envelope errors on /v1/*; do not expect the same JSON shape on both surfaces.
  • Distinguish invalid_token (refresh the token) from upstream_unavailable (retry later).
  • Check coarse availability with GET /status.
  • Confirm you are on the expected major version via GET /versions and /openapi/v1.json.