Error Handling

​

Error Handling

{
  "error": "ERROR_CODE",
  "message": "Human-readable description"
}

​

Error Reference

​

400 Bad Request

• Cause: Missing or malformed required fields in the request body
• Solution: Verify all required parameters are present and correctly formatted

• Cause: A v2 signing endpoint was called for a v1 wallet without supplying encryption_context
• Solution: Include encryption_context on the first v2 call for that wallet. See the migration guide

​

401 Unauthorized

• Cause: The access_key or op_jwt is invalid, or iss/sub in the op_jwt does not match the wallet’s identity binding
• Solution: Verify access_key is the value returned at wallet creation. Ensure the JWT is signed by the same identity that created the wallet — iss and sub must be byte-identical

​

403 Forbidden

• Cause: The x-magic-secret-key header is missing
• Solution: Include x-magic-secret-key: sk_live_XXXXXXXX on every request

• Cause: The secret key is invalid or does not match a known application
• Solution: Verify your secret key in the Magic Dashboard

​

404 Not Found

• Cause: The wallet_id does not exist or does not belong to your application
• Solution: Verify the wallet ID was created by your application

​

429 Too Many Requests

• Cause: Exceeded the rate limit of 25 requests/second
• Solution: Back off and retry. Implement exponential backoff for bursts

​

500 Internal Server Error

• Cause: An unexpected error occurred, including JWT validation failures inside the enclave (expired token, unknown kid, forbidden header parameter, binding mismatch)
• Solution: Check that your op_jwt is not expired, uses a supported issuer, and has kid in the header. If the issue persists, contact Magic support

​

503 Service Unavailable

• Cause: The enclave pool is overloaded
• Solution: Retry with exponential backoff

​

Best Practices