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

# Errors and Operational Notes

> Common status codes, error payload shape, and integration guidance

Most error responses use a flexible `ErrorResponse` payload. The exact fields can vary by handler, so integrations should parse defensively.

## Common Error Shape

Every error response includes:

```json theme={null}
{
  "status": "error"
}
```

Depending on the endpoint, the payload may also include:

* `error`
* `reason`
* `detail`
* `field`
* `currency`
* `missing`
* `errors`
* `message`
* `constraint`
* `tx_status`
* `project_uid`
* `widget_id`
* `expected`

## Typical Status Codes

| Code  | Meaning                          | Common Cases                                                                 |
| ----- | -------------------------------- | ---------------------------------------------------------------------------- |
| `400` | Invalid request                  | Missing fields, invalid ids, or redirect not available for the current state |
| `403` | Forbidden                        | Invalid signature, inactive project, or wallet ownership failure             |
| `404` | Not found                        | Project, network, widget, or transaction does not exist                      |
| `422` | Validation or processing failure | Project creation failures or invalid transaction creation input              |
| `500` | Internal failure                 | On-chain status checker or backend processing error                          |

## Validation Errors

Some handlers return an `errors` object that maps field names to one or more messages.

Plan for both patterns below:

```json theme={null}
{
  "status": "error",
  "error": "invalid_request"
}
```

```json theme={null}
{
  "status": "error",
  "errors": {
    "amount": ["must be greater than zero"]
  }
}
```

## Integration Recommendations

* treat transaction ids and project ids as opaque values;
* log both HTTP status and the full error body;
* preserve raw request bodies for signed transaction debugging;
* retry only when the failure mode is transient or operationally recoverable;
* keep callback replay tooling available for downstream recovery.

## Operational Checklist

* validate networks and currencies before project creation;
* store `secret_key` safely when a project is created;
* cap paginated reads with `limit` and `offset`;
* handle both success JSON and `302` redirect responses in your client code.