ParaLens API Errors — Status Codes and Error Handling

When a ParaLens request fails, the API returns a JSON body with an error field and an appropriate HTTP status code. This page documents all error conditions and how to handle them in your integration.

Error Response Shape

All error responses share a consistent envelope:

{ "error": "message" }

Status Codes

Status	Meaning	Action
`200`	Success	Parse `TxReport`
`400`	Bad Request	Fix input (invalid hash or chain)
`502`	Bad Gateway	Retry — upstream failure

400 Bad Request

A 400 is returned when the request body is invalid. These errors are user-correctable — the request must be fixed before retrying. Common causes

Invalid hash format

The tx_hash value could not be parsed as a valid Ethereum transaction hash.

{ "error": "invalid tx_hash `abc`" }

Resolution: Ensure the hash is exactly 66 characters — 0x followed by 64 lowercase hex characters.

Unsupported chain

The chain value provided is not currently supported by ParaLens.

{ "error": "unsupported chain `polygon` (only `ethereum` is supported)" }

Resolution: Set chain to one of the accepted identifiers: ethereum, mainnet, eth, or 1.

502 Bad Gateway

A 502 is returned when an upstream dependency fails during analysis. These errors are retryable — the request itself is valid, but a transient failure prevented a result from being produced. Common causes

RPC node unavailable or congested
Transaction trace unavailable (very old transactions, unsupported trace format)
Analysis engine failure during complex trace processing

Example

{ "error": "analysis failed: rpc connection refused" }

Resolution: Retry after a short delay. If the error persists for a specific transaction hash, the transaction may have an unsupported trace format and cannot currently be analyzed.

Client Error Handling

The snippet below demonstrates a robust fetch wrapper that distinguishes user-correctable 400 errors from retryable 502 failures:

async function analyzeWithErrorHandling(txHash: string) {
  const res = await fetch('https://paralens-production.up.railway.app/analyze', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ chain: 'ethereum', tx_hash: txHash }),
  });

  const data = await res.json();

  if (res.status === 400) {
    // User-correctable: invalid hash or unsupported chain
    throw new Error(`Invalid request: ${data.error}`);
  }

  if (res.status === 502) {
    // Retryable: upstream RPC or analysis failure
    throw new Error(`Analysis failed (retryable): ${data.error}`);
  }

  if (!res.ok) {
    throw new Error(`Unexpected error: ${data.error}`);
  }

  return data; // TxReport
}

Display Guidance

How you surface errors to users depends on your product context:

Developer tools — display the raw error field value directly. The messages are precise and actionable for engineers debugging an integration.
Consumer UIs — replace technical errors with friendly copy:
- 400 → “Please enter a valid Ethereum transaction hash.”
- 502 → “Analysis temporarily unavailable — please try again.”

Endpoints

Response Schema

Reference

ParaLens API Errors — Status Codes and Error Handling

Error Response Shape

Status Codes

400 Bad Request

502 Bad Gateway

Client Error Handling

Display Guidance

​Error Response Shape

​Status Codes

​400 Bad Request

​502 Bad Gateway

​Client Error Handling

​Display Guidance

Error Response Shape

Status Codes

400 Bad Request

502 Bad Gateway

Client Error Handling

Display Guidance