Skip to main content
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: 
{
  "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.