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

# Error Reference

> All TxShield API error codes and how to handle them

## Overview

Every error response from TxShield follows this structure:

```json theme={null}
{
  "success": false,
  "error": "Human-readable error message here"
}
```

Always check `success` first. If `false`, read `error` for the exact reason.

***

## HTTP Status Codes

### 400 — Bad Request

Your request is missing required fields or has invalid values.

```json theme={null}
{ "success": false, "error": "targetContractAddress is required" }
{ "success": false, "error": "chainId is required" }
{ "success": false, "error": "Wallet and signature required" }
```

**Fix:** Check your request body includes both `targetContractAddress` and `chainId`.

***

### 401 — Unauthorized

No API key was provided.

```json theme={null}
{ "success": false, "error": "Missing Authorization header" }
{ "success": false, "error": "Invalid Authorization format" }
```

**Fix:** Add `Authorization: Bearer txs_your_api_key_here` to your request headers.

***

### 403 — Forbidden

Your API key is invalid or has been revoked.

```json theme={null}
{ "success": false, "error": "Invalid API key" }
```

**Fix:** Verify your key at [txshield.xyz/api-keys](https://txshield.xyz/api-keys).
If lost, reconnect your wallet to regenerate.

***

### 429 — Rate Limit Exceeded

You have exceeded your tier's request limit.

```json theme={null}
{ "success": false, "error": "Too many requests, slow down." }
{ "success": false, "error": "Analysis rate limit hit. Max 10 requests per minute." }
```

**Fix:** Wait for the 60-second window to reset. If you need higher limits,
contact us for a partner tier key.

| Endpoint Type                                     | Limit        |
| ------------------------------------------------- | ------------ |
| `/api/simulate`, `/api/honeypot`, `/api/phishing` | 10 req / min |
| All other endpoints                               | 30 req / min |

***

### 500 — Internal Server Error

Something failed on our end — RPC node issue, simulation failure, or unexpected error.

```json theme={null}
{ "success": false, "error": "Simulation failed" }
{ "success": false, "error": "Honeypot check failed" }
{ "success": false, "error": "Server error" }
```

**Fix:** Retry the request. If it persists, check our status on
[X @txshield\_](https://x.com/txshield_) or email
[contactcodecommunity@gmail.com](mailto:contactcodecommunity@gmail.com).

***

## Handling Errors in Code

```javascript theme={null}
const res = await fetch('https://api.txshield.xyz/api/simulate/execute-simulation', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer txs_your_api_key_here'
  },
  body: JSON.stringify({ targetContractAddress, chainId })
});

const data = await res.json();

if (!data.success) {
  switch (res.status) {
    case 400: console.error('Bad request:', data.error); break;
    case 401: console.error('No API key provided'); break;
    case 403: console.error('Invalid API key'); break;
    case 429: console.error('Rate limit hit — back off and retry'); break;
    case 500: console.error('TxShield server error — retry later'); break;
    default:  console.error('Unknown error:', data.error);
  }
  return;
}

// Safe to use data here
```

***

<CardGroup cols={2}>
  <Card title="Authentication" icon="lock" href="/authentication">
    How to generate and use your API key correctly.
  </Card>

  <Card title="Contact Us" icon="phone" href="/contact-us">
    Persistent errors? Reach out to the team.
  </Card>
</CardGroup>