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.

Token introspection (POST /oauth/introspect) is reserved for internal and trusted partner integrations. It is not part of the normal public developer workflow.

/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 and may contain field-level validation entries.
  • request_id is not included in error responses today. Do not depend on it in client logic.

Validation error example

When semantic validation fails, data.details may list affected fields (shape used across MusiMap services as endpoints ship): 

{
  "status": 422,
  "message": "Validation failed.",
  "data": {
    "error_code": "validation_error",
    "details": [
      {
        "field": "source_type",
        "code": "invalid_choice",
        "message": "Unsupported source type."
      }
    ]
  }
}

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 bad_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. Request a token with the correct scope.
403 forbidden The caller is authenticated but not allowed to perform this action. Check organisation, catalog, and resource access.
404 not_found The resource does not exist or is outside your access scope. Verify the resource id and catalogue context.
409 conflict The resource state does not allow this operation. Refresh the resource state and retry appropriately.
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.
  • Do not rely on operational probe endpoints (/live, /ready) for customer integrations. Use /status instead.