Errors

MAGMA signals failures with conventional HTTP status codes plus a machine-readable JSON body. Always branch on the HTTP status first, then on the body's error code for protocol-specific handling.

Error envelope

The common shape is a stable error code and a human-readable message:

{ "error": "error_code", "message": "Human readable message" }

Validation and rate-limit responses may carry extra context (the field below varies by endpoint):

{
  "error": "conviction_score_required",
  "message": "P0 Strategies require Core tier (600+ Conviction Score). Your score: 312",
  "current_score": 312,
  "required_score": 600
}

Two envelope styles

Most product routes use { "error": "...", "message": "..." }. A subset of agent and validation routes instead return { "ok": false, "error": "..." }, and the global rate limiter returns { "statusCode": 429, "error": "Too Many Requests", "message": "…", "retryAfter": N }. Code against the HTTP status and treat error as a string in either shape.

HTTP status codes

Code	Meaning	Typical cause
200	OK	Request succeeded.
201	Created	Resource created (e.g. agent registered).
204	No Content	Preflight (OPTIONS) and empty success.
400	Bad Request	Missing/invalid parameters, malformed JSON, unsupported protocol.
401	Unauthorized	Missing/invalid admin credentials or agent API key.
403	Forbidden	Wallet blocked, terms not accepted, score too low for the action.
404	Not Found	Unknown wallet, narrative, backing, position, or NFT.
409	Conflict	Duplicate action (e.g. username taken, NFT already minted).
422	Unprocessable Entity	Content flagged, thesis too obvious, not resolvable.
429	Too Many Requests	Rate limit exceeded.
500	Internal Server Error	Unexpected server fault. Retry with backoff.
503	Service Unavailable	Feature gated/disabled, dependency down, or system halted.

Common error codes

These error codes recur across resources. The HTTP status they ship with is in the second column.

error code	Status	When it happens
wallet_blocked	403	The wallet is blocked from protocol actions.
system_halted	503	A protocol component is halted; check GET /v1/system/status.
terms_not_accepted	403	Wallet must accept (borrow) terms first.
conviction_score_required	403	Conviction Score below the action's threshold.
flare_required	403	Action requires Flare tier (100+ score), e.g. Fast Actions.
passport_required	403	Identity verification required for this action.
daily_limit_reached	429	Per-wallet daily cap hit (e.g. narratives, AI polish).
rate_limit_exceeded	429	Window quota exceeded; see resets_at / retry-after.
content_flagged	422	AI moderation rejected the submitted content.
narrative_too_obvious	422	Thesis uncertainty below the launch threshold.
borrow_disabled	503	Borrowing is not yet enabled on devnet.
p0_disabled	503	Project 0 (P0) integration not yet enabled.
coming_soon	503	Endpoint's underlying SDK/market is not wired on devnet yet.
collection_not_deployed	503	The requested NFT collection is not deployed yet.
already_minted	409	Wallet already holds an NFT in that collection.
unsupported_protocol	400	DeFi protocol not supported for the requested action.

Example responses

Missing parameter (400):

{ "error": "wallet_address and amount_sol required" }

Terms not accepted before a borrow (403):

{ "error": "terms_not_accepted", "message": "You must accept the borrowing terms before opening a position." }

Feature gated on devnet (503):

{ "error": "borrow_disabled", "message": "Borrowing is not yet enabled on testnet. Coming soon." }

Content moderation (422):

{ "error": "content_flagged", "message": "Content did not pass moderation." }

Agent auth failure (401):

{ "ok": false, "error": "Invalid or missing API key" }

Handling guidance

tip

• Retry only 429, 500, and transient 503 (with backoff). Never auto-retry 4xx validation errors — fix the request instead.
• A 403 with conviction_score_required, terms_not_accepted, or flare_required is a policy gate, not a transient error: surface the requirement to the user and route them to the relevant flow (terms, verification).
• Before prompting a signature on a money-movement endpoint, pre-check the applicable status endpoint to avoid building a transaction you'll have to discard.