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.

Validation errors

{
  "status": 422,
  "error": "Unprocessable Entity",
  "code": "validation_errors",
  "error_details": {
    "code": [
      "value_is_mandatory"
    ]
  }
}

Error fields

status · number · required

The HTTP status code.

error · string · required

A generic error message.

code · string

A generic error code representing the type of error.

provider.code · string

The code of the payment provider that caused the error when applicable.

error_details · 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.

Error codes

bad_request_error

{ "status": 400, "error": "BadRequest: [error.message]" }

Examples:

• coupons_must_be_an_array
• subscriptions_must_be_an_object

unauthorized_error

{ "status": 401, "error": "[message]" }

Examples:

• Unauthorized
• expired_jwt_token

forbidden_error

{ "status": 403, "error": "Forbidden", "code": "[error_code]" }

Examples:

• feature_unavailable
• feature_not_available
• [mode]_action_not_allowed_for_[resource_name]

not_found_error

{ "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

{ "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

{ "status": 422, "error": "Unprocessable Entity", "code": "validation_errors", "error_details": [validation_errors] }

provider_error

{ "status": 422, "error": "Unprocessable Entity", "code": "provider_error", "provider": { "code": "[provider_code]" }, "error_details": [serialized_error] }

third_party_error

{ "status": 422, "error": "Unprocessable Entity", "code": "third_party_error", "error_details": { "third_party": "[third_party]", "thirdparty_error": "[error_message]" } }

stripe_required_error

{ "status": 422, "error": "Unprocessable Entity", "code": "stripe_required", "message": "Only Stripe is supported for authorization" }

too_many_provider_requests_error

{ "status": 429, "error": "Too Many Provider Requests", "code": "too_many_provider_requests", "error_details": { "provider_name": "[provider_name]", "message": "[message]" } }

internal_server_error

{ "status": 500, "errors": [{ "message": "[error_message]", "backtrace": [backtrace] }], "data": {} }

health_check_error

{ "version": "[version]", "github_url": "[url]", "message": "Unhealthy", "details": "[error_message]" }