> ## Documentation Index
> Fetch the complete documentation index at: https://paralens.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ParaLens API Errors — Status Codes and Error Handling

> Complete reference for ParaLens API error responses — status codes, error messages, and how to handle 400 and 502 errors in your integration.

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:

```json theme={null}
{ "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**

<AccordionGroup>
  <Accordion title="Invalid hash format">
    The `tx_hash` value could not be parsed as a valid Ethereum transaction hash.

    ```json theme={null}
    { "error": "invalid tx_hash `abc`" }
    ```

    **Resolution:** Ensure the hash is exactly 66 characters — `0x` followed by 64 lowercase hex characters.
  </Accordion>

  <Accordion title="Unsupported chain">
    The `chain` value provided is not currently supported by ParaLens.

    ```json theme={null}
    { "error": "unsupported chain `polygon` (only `ethereum` is supported)" }
    ```

    **Resolution:** Set `chain` to one of the accepted identifiers: `ethereum`, `mainnet`, `eth`, or `1`.
  </Accordion>
</AccordionGroup>

***

## 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**

```json theme={null}
{ "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:

```ts theme={null}
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."*