Error Handling

Every /v2 failure returns a structured problem detail object conforming to RFC 9457, with the application/problem+json content type. This makes errors machine-readable and consistent across every endpoint, the auth gate, and framework failures.

Problem Detail Fields

Field	Type	Present	Description
`type`	string	Always	A URI that identifies the problem type. Stable across environments.
`title`	string	Always	A short, human-readable summary of the problem type.
`status`	number	Always	The HTTP status code.
`detail`	string	Always	A human-readable explanation specific to this occurrence.
`instance`	string	Always	The absolute URL of the failed request, with the `/v2` mount prefix and no query string.
`correlationId`	string	Always	A ULID that identifies this request. It matches the `Correlation-Id` response header.
`details`	object	Optional	Domain fields for the condition, for example `id`, `field`, `chainId`, or `keyEnv`.

{
  "type": "https://docs.mure.app/problems/transfer-not-found",
  "title": "Transfer not found",
  "status": 404,
  "detail": "Transfer with ID int_transfer_01HT... not found",
  "instance": "https://api.mure.app/v2/transfers/int_transfer_01HT...",
  "correlationId": "01J0000000000000000000000A",
  "details": { "id": "int_transfer_01HT..." }
}

Problem types

type is always https://docs.mure.app/problems/<slug>. The value is the same in sandbox, production, and local: it identifies the problem type, not the failed request. Each URI resolves to a page under Problems.

Slug	Status	Meaning
`bad-request`	400	The request could not be parsed or contained an invalid payload.
`missing-api-key`	401	No API key was supplied.
`invalid-api-key`	403	The supplied API key is not valid.
`chain-not-allowed-for-key-environment`	403	The chain is not allowed for the API key's environment.
`rate-limited`	429	Too many requests.
`route-not-found`	404	No route matched the request.
`transfer-not-found`	404	The requested transfer does not exist.
`validation-failed`	422	The request failed domain validation.
`transfer-service-failure`	500	The transfer could not be completed.
`token-registry-service-failure`	500	The token registry could not be read.
`upstream-failure`	503	An upstream dependency failed.
`internal-error`	500	An unexpected server-side error occurred.

Correlation

Every response carries a Correlation-Id header. When a problem body is present, its correlationId equals the header. Server-side logs use the same value. Include it when you contact support.

HTTP Status Codes

Status	Meaning	Typical Scenarios
400	Bad Request	Malformed JSON or a payload that fails schema validation.
401	Unauthorized	Missing `api-key` header.
403	Forbidden	Invalid API key, or the key's environment does not match the requested chain.
404	Not Found	The route does not exist, or the resource does not exist for the given ID.
422	Unprocessable Content	Domain validation failure.
429	Too Many Requests	Rate limit exceeded. Honor the `Retry-After` header value.
500	Internal Server Error	Unexpected server-side failure. Contact support if persistent.
503	Service Unavailable	An upstream dependency failed. Honor the `Retry-After` header value.