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

# Errors

The Lago API uses standard HTTP response codes to clearly indicate the result of each API request:

* **2xx**: Success - The request was processed successfully.
* **4xx**: Client Error - There was an issue with the request, such as missing parameters, invalid input, or unauthorized access.
* **5xx**: Server Error - An error occurred on Lago's side while processing the request.

For some 4xx errors, the response body will include additional information to help you understand and resolve the specific problem.

<ResponseExample>
  ```json Validation errors theme={"dark"}
  {
    "status": 422,
    "error": "Unprocessable Entity",
    "code": "validation_errors",
    "error_details": {
      "code": [
        "value_is_mandatory"
      ]
    }
  }
  ```

  ```json Not found theme={"dark"}
  {
    "status": 404,
    "error": "Not Found",
    "code": "subscription_not_found"
  }
  ```

  ```json Forbidden theme={"dark"}
  {
    "status": 403,
    "error": "Forbidden",
    "code": "feature_unavailable"
  }
  ```

  ```json Unauthorized theme={"dark"}
  {
    "status": 401,
    "error": "Unauthorized"
  }
  ```
</ResponseExample>

## Error fields

<ResponseField name="status" type="number" required>
  The HTTP status code.
</ResponseField>

<ResponseField name="error" type="string" required>
  A generic error message.
</ResponseField>

<ResponseField name="code" type="string">
  A generic error code representing the type of error.
</ResponseField>

<ResponseField name="provider.code" type="string">
  The code of the payment provider that caused the error when applicable.
</ResponseField>

<ResponseField name="error_details" type="object">
  An object containing the error details. It usually maps the field names that caused the error to an array of
  error messages/codes.

  For specific errors, such as a payment provider error, the `error_details` may include other fields.
</ResponseField>

## Error codes

### bad\_request\_error

```json theme={"dark"}
{ "status": 400, "error": "BadRequest: [error.message]" }
```

**Examples:**

* `coupons_must_be_an_array`
* `subscriptions_must_be_an_object`

### unauthorized\_error

```json theme={"dark"}
{ "status": 401, "error": "[message]" }
```

**Examples:**

* `Unauthorized`
* `expired_jwt_token`

### forbidden\_error

```json theme={"dark"}
{ "status": 403, "error": "Forbidden", "code": "[error_code]" }
```

**Examples:**

* `feature_unavailable`
* `feature_not_available`
* `[mode]_action_not_allowed_for_[resource_name]`

### not\_found\_error

```json theme={"dark"}
{ "status": 404, "error": "Not Found", "code": "[resource]_not_found" }
```

**Examples:**

* `invoice_not_found`
* `customer_not_found`
* `subscription_not_found`
* `billing_entity_not_found`
* `plan_not_found`
* `add_on_not_found`
* `coupon_not_found`
* `tax_not_found`
* `feature_not_found`
* `privilege_not_found`
* `billable_metric_not_found`
* `webhook_endpoint_not_found`
* `api_log_not_found`
* `activity_log_not_found`
* `payment_not_found`
* `payment_receipt_not_found`
* `fee_not_found`
* `event_not_found`
* `credit_note_not_found`
* `wallet_not_found`
* `wallet_transaction_not_found`
* `lifetime_usage_not_found`
* `alert_not_found`
* `entitlement_not_found`

### method\_not\_allowed\_error

```json theme={"dark"}
{ "status": 405, "error": "Method Not Allowed", "code": "[error_code]" }
```

**Examples:**

* `feature_not_supported`
* `invalid_type_or_status`
* `credit_note_voided`
* `no_voidable_amount`
* `invoices_not_overdue`
* `invoices_have_different_currencies`
* `invoices_not_ready_for_payment_processing`
* `premium_integration_missing`
* `metadata_on_draft_invoice`
* `payment_status_update_on_draft_invoice`
* `not_voidable`
* `is_draft`
* `invalid_status`
* `last_admin`
* `cannot_revoke_own_membership`
* `enabled_authentication_methods_required`
* `signup_disabled`
* `plan_overlapping`
* `wallet_not_active`
* `is_succeeded`
* `no_active_subscription`
* `status_not_voided`
* `invoice_not_finalized`
* `invoice_payment_already_succeeded`
* `invoice_due_date_in_future`
* `invoice_dispute_lost`
* `payment_processor_is_currently_handling_payment`
* `invoiced_fee`
* `eu_tax_not_applicable`
* `not_disputable`
* `only_one_limitation_type_per_coupon_allowed`

### validation\_errors

```json theme={"dark"}
{ "status": 422, "error": "Unprocessable Entity", "code": "validation_errors", "error_details": [validation_errors] }
```

### provider\_error

```json theme={"dark"}
{ "status": 422, "error": "Unprocessable Entity", "code": "provider_error", "provider": { "code": "[provider_code]" }, "error_details": [serialized_error] }
```

### third\_party\_error

```json theme={"dark"}
{ "status": 422, "error": "Unprocessable Entity", "code": "third_party_error", "error_details": { "third_party": "[third_party]", "thirdparty_error": "[error_message]" } }
```

### stripe\_required\_error

```json theme={"dark"}
{ "status": 422, "error": "Unprocessable Entity", "code": "stripe_required", "message": "Only Stripe is supported for authorization" }
```

### too\_many\_provider\_requests\_error

```json theme={"dark"}
{ "status": 429, "error": "Too Many Provider Requests", "code": "too_many_provider_requests", "error_details": { "provider_name": "[provider_name]", "message": "[message]" } }
```

### internal\_server\_error

```json theme={"dark"}
{ "status": 500, "errors": [{ "message": "[error_message]", "backtrace": [backtrace] }], "data": {} }
```

### health\_check\_error

```json theme={"dark"}
{ "version": "[version]", "github_url": "[url]", "message": "Unhealthy", "details": "[error_message]" }
```