# Error Taxonomy

API errors use this shape:

```json
{
  "error": {
    "code": "provider_failed",
    "message": "Instagram provider failed to return post data.",
    "requestId": "req_..."
  }
}
```

## Auth And Access

| Code | HTTP | Meaning | Action |
| --- | ---: | --- | --- |
| `unauthorized` | 401 | Missing or invalid API key. | Check `Authorization: Bearer igsk_...`. |
| `forbidden` | 403 | Owner/admin key required. | Use owner key only for ops/admin. |
| `invalid_invite` | 403 | Signup invite code missing or wrong. | Use the configured invite code. |

## Request Validation

| Code | HTTP | Meaning | Action |
| --- | ---: | --- | --- |
| `invalid_request` | 400 | Invalid JSON body. | Fix request fields. |
| `invalid_query` | 400 | Invalid query parameter. | Use documented values and limits. |
| `type_mismatch` | 400 | URL does not match endpoint type. | Use post URL for `/v1/post`, reel URL for `/v1/reel`. |
| `ambiguous_input` | 400 | Bare id cannot be resolved for this endpoint. | Provide a full Instagram URL. |
| `unsupported_host` | 400 | Non-Instagram URL. | Use an instagram.com URL. |
| `unsupported_shape` | 400 | Unsupported Instagram URL shape. | Use post/reel/comment-supported URLs. |

## Billing And Limits

| Code | HTTP | Meaning | Action |
| --- | ---: | --- | --- |
| `insufficient_credits` | 402 | Account lacks reserved credits. | Top up or use owner smoke key. |
| `usage_limit_exceeded` | 400 | Request exceeds configured limits. | Lower comment limit or remove expensive options. |
| `rate_limit_exceeded` | 429 | Per-minute or daily spend guardrail hit. | Retry later or reduce scope. |
| `stripe_not_configured` | 503 | Checkout/webhook missing Stripe config. | Configure Stripe env vars. |
| `stripe_checkout_failed` | 502 | Stripe checkout API failed. | Retry later and inspect operator logs. |
| `invalid_signature` | 400 | Stripe webhook signature failed. | Check webhook secret and raw payload handling. |
| `invalid_webhook` | 400 | Webhook payload shape invalid. | Verify Stripe event body. |
| `invalid_topup_metadata` | 400 | Checkout metadata cannot grant credits. | Verify `accountId` and `microCredits`. |

## Upstream And Parse

| Code | HTTP | Meaning | Action |
| --- | ---: | --- | --- |
| `provider_not_configured` | 503 | No provider is configured. | Set provider env vars. |
| `provider_failed` | 502 | Provider failed to return data. | Retry narrower request or switch provider config. |
| `parser_not_configured` | 503 | Hosted parser endpoint missing. | Configure Achronon AI endpoint/token or omit parse. |
| `upstream_failed` | 502 | Provider or parser dependency failed. | Inspect limitations/logs, then retry if appropriate. |

## Refund Rule

If igskill reserves credits and provider/parser work fails before usable data is returned, refund the reservation. If partial data is returned, expose `usage` and `limitations` so callers can decide whether to retry.