API Errors - mpcvault

Error Response Format

REST maps gRPC errors to non-2xx HTTP statuses, with top-level code and message fields. For example, a rate-limit rejection returns HTTP 429:

{
  "code": 8,
  "message": "rate limit exceeded",
  "details": []
}

An HTTP 200 response can also contain a business error object. Check both the HTTP status and error; the response schema defines its service-level or endpoint-specific error fields.

Service-level Errors

Service-level errors use error.serviceErrorCode and can be shared across endpoints. The API contract defines the following code for an organization’s pending signing request limit:

Code	Value	Message
`SERVICE_ERROR_CODE_ORG_PENDING_SIGNING_REQUEST_LIMIT_EXCEEDED`	`5`	Too many pending signing requests. Please reject some before creating new ones.

If this error is returned, reject pending signing requests before retrying creation. It is separate from request-rate limiting; automatic retries alone do not resolve it.

Common Error Codes

Code	Description
`INVALID_ARGUMENT`	Missing or invalid request parameters
`NOT_FOUND`	Resource (wallet, signing request) not found
`PERMISSION_DENIED`	API token lacks required permissions
`UNAUTHENTICATED`	Missing or invalid API token
`ALREADY_EXISTS`	Resource already exists (e.g., duplicate ref)
`FAILED_PRECONDITION`	Operation not allowed in current state
`RESOURCE_EXHAUSTED`	Request rate or resource limit exceeded
`INTERNAL`	Internal server error

HTTP Status Codes

Status	Meaning
`200`	Transport succeeded; check the response `error` field
`400`	Bad request - check your parameters
`401`	Unauthorized - check your API token
`403`	Forbidden - insufficient permissions
`404`	Not found
`429`	Rate limited - slow down requests
`500`	Server error - retry later

Rate limits

Enforced rate limits return HTTP 429 or gRPC RESOURCE_EXHAUSTED with rate limit exceeded. Retry with exponential backoff and jitter; the API currently returns no retry interval. Request limits are managed by MPCVault and can differ by API. For retried writes, follow Idempotency.

Handling Errors

import requests

response = requests.post(
    "https://api.mpcvault.com/v1/getWalletList",
    headers={"x-mtoken": "YOUR_API_TOKEN"},
    json={"vaultUuid": "<VAULT_UUID>"}
)

payload = response.json()
if not response.ok:
    print(f"API error {payload.get('code')}: {payload.get('message')}")
elif payload.get("error"):
    print(f"Request rejected: {payload['error']}")