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

# Error Model

> How Guppy standardizes real-world failure

Guppy treats errors as first-class citizens. Real-world execution is messy, and our error model reflects that.

## Standard Error Envelope

When an API request fails, Guppy returns a JSON response of the form:

```json theme={null}
{
  "error": {
    "type": "invalid_request",
    "code": "MISSING_REQUIRED_FIELD",
    "message": "external_user_id is required",
    "request_id": "req_123",
    "retryable": false,
    "details": {
      "field": "external_user_id"
    }
  }
}
```

### Error Fields

* `type`: broad category (e.g., `invalid_request`, `auth`, `rate_limited`, `conflict`, `server_error`)
* `code`: stable machine-readable code
* `message`: human-readable message (safe to display to developers)
* `request_id`: identifier to help support trace the request
* `retryable`: whether automatic retries may succeed
* `details`: optional structured metadata

### Common Failure Reasons

* `OUT_OF_STOCK`: The product is no longer available at the target merchant.
* `PRICE_CHANGED`: The current price exceeds the provided guardrails.
* `PAYMENT_DECLINED`: The funding source was rejected by the merchant.
* `BLOCKED_ANTIBOT`: The merchant's bot protection prevented execution.
* `TIMEOUT`: Execution took longer than the allowed window.
* `MERCHANT_ERROR`: A generic failure on the merchant's side.

## HTTP Status Codes

Common status codes you should handle:

* `400`: Invalid request (bad schema, missing/invalid fields)
* `401`: Missing/invalid API key
* `403`: Key not allowed for this resource/action
* `404`: Resource not found
* `409`: Conflict (e.g., idempotency conflict or invalid state transition)
* `429`: Rate limited (honor `Retry-After` when provided)
* `5xx`: Server error (retry with backoff)

### Recovery

Failures in Guppy are **typed** and **recoverable** whenever possible. If an intent fails with a recoverable error (e.g., `TIMEOUT`), Guppy may automatically retry based on the provided `retry_policy`.