ERROR RESPONSES

Neura uses consistent, machine readable error envelopes so you can gracefully handle failures. This page summarizes available HTTP status codes, the JSON schema, and troubleshooting pointers.

Envelope format

{
  "success": false,
  "error": "Human readable message",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "retryAfter": 5,          // Optional, present on 429 responses
  "details": { "...": "..." } // Optional, additional structured data
}

• success is always false when an error occurs.

• error contains a message you can display in dashboards or logs.

• timestamp uses ISO 8601 format (UTC).

• retryAfter appears when the client should wait before retrying, measured in seconds.

• details may appear on certain validation errors to highlight which field failed.

HTTP status codes

Status	Scenario	Suggested handling
200 with success: false	Business logic failure (for example, token not found).	Inspect error and decide whether to retry or surface the message.
400	Validation failure (missing parameters, bad formats).	Correct the payload and retry.
401	Authentication failure (invalid or missing payment proof).	Re-run the payment flow, ensure headers match the invoice.
402	Payment required (discovery response).	Settle the invoice and replay with proof headers.
403	Forbidden (rare; indicates access restrictions).	Contact Neura support.
404	Endpoint not found or disabled.	Check the path and prefix.
429	Rate limit exceeded.	Wait retryAfter seconds and retry with backoff.
500	Internal server error.	Retry with backoff. Persistent failures should be escalated.
503	Temporary service degradation.	Retry after a short delay.

Validation messages

Typical validation errors include:

• "walletAddress is required"

• "networks array is required and must not be empty"

• "Search query (q) is required and must be a non-empty string"

• "From timestamp must be less than to timestamp"

Check for these strings in error and surface them to end users when appropriate.

Payment errors

• Repeated 402 responses: Ensure the invoice is settled on the correct network and include the full set of X402 headers (X-402-Invoice, X-402-Payment-Proof, X-402-Version, etc.). Re-read the Coinbase X402 welcome guide for header details.

• 401 Unauthorized: Indicates that the payment proof or headers were malformed. Generate a fresh payment proof after settling the invoice again.

• Facilitator errors: The facilitator response body often includes actionable error codes. Log these responses for support.

Rate limiting

429 responses look like:

{
  "success": false,
  "error": "Rate limit exceeded",
  "retryAfter": 5,
  "timestamp": "2025-01-15T12:40:00.000Z"
}

Honor the retryAfter value and apply exponential backoff with jitter. If rate limiting persists, consider staggering client traffic or caching responses client side.

Escalation

If you encounter persistent 5xx errors or suspect an outage:

1. Capture the request path, correlation ID (if present), and full response body.

2. Include payment metadata such as invoice hash and settlement transaction hash.

3. Reach out to Neura support through your designated channel with the captured information.