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

# Error Codes

> Complete reference for all API error codes and how to handle them

Every failed request carries a `code`: a stable, machine-readable identifier for what went wrong. This page lists them all.

```json theme={null}
{
  "success": false,
  "message": "The request contains invalid parameters",
  "code": "ValidationError",
  "data": null
}
```

<Note>
  For the response envelope itself, validation errors and HTTP status codes, see
  [Responses & Errors](/api-reference/responses).
</Note>

## Error Codes Reference

### Authentication & Authorization

<AccordionGroup>
  <Accordion title="AccessDenied" icon="ban">
    **HTTP Status:** 403 Forbidden

    **Description:** You don't have permission to access this resource or perform this action.

    **Common causes:**

    * API key lacks required scope
    * Trying to access another user's resources
    * Account restrictions or suspensions
    * Store-level permissions insufficient

    **How to fix:**

    * Check your API key has the necessary [scopes](/api-reference/scopes)
    * Verify you're accessing resources you own
    * Check account status in dashboard
    * Request additional permissions if needed

    **Example:**

    ```json theme={null}
    {
      "success": false,
      "message": "Your API key does not have permission to update products",
      "code": "AccessDenied",
      "data": null
    }
    ```
  </Accordion>

  <Accordion title="BadToken" icon="key">
    **HTTP Status:** 401 Unauthorized

    **Description:** The provided authentication token is invalid, expired, or malformed.

    **Common causes:**

    * Expired API key
    * Revoked API key
    * Malformed Authorization header
    * API key not found

    **How to fix:**

    * Generate a new API key from dashboard
    * Verify Authorization header format: `Bearer YOUR_API_KEY`
    * Check for whitespace or special characters in token
    * Ensure API key hasn't been revoked

    **Example:**

    ```json theme={null}
    {
      "success": false,
      "message": "The provided API key is invalid or has expired",
      "code": "BadToken",
      "data": null
    }
    ```
  </Accordion>

  <Accordion title="TwoFactorRequired" icon="shield">
    **HTTP Status:** 403 Forbidden

    **Description:** Two-factor authentication is required for this action.

    **Common causes:**

    * Sensitive operation requires 2FA
    * Account security policy enforced
    * Administrative action attempted

    **How to fix:**

    * Complete 2FA challenge
    * Enable 2FA on your account
    * Use session-based authentication for sensitive operations

    **Example:**

    ```json theme={null}
    {
      "success": false,
      "message": "This operation requires two-factor authentication",
      "code": "TwoFactorRequired",
      "data": null
    }
    ```
  </Accordion>

  <Accordion title="OAuthLoginRequired" icon="arrow-right-to-bracket">
    **HTTP Status:** 401 Unauthorized

    **Description:** OAuth authentication is required for this endpoint.

    **Common causes:**

    * Endpoint requires user session, not API key
    * OAuth flow not completed
    * Session expired

    **How to fix:**

    * Complete OAuth authentication flow
    * Use correct authentication method for endpoint
    * Check if endpoint supports API key authentication

    **Example:**

    ```json theme={null}
    {
      "success": false,
      "message": "This endpoint requires OAuth authentication",
      "code": "OAuthLoginRequired",
      "data": null
    }
    ```
  </Accordion>
</AccordionGroup>

### Validation & Input Errors

<AccordionGroup>
  <Accordion title="ValidationError" icon="triangle-exclamation">
    **HTTP Status:** 400 Bad Request

    **Description:** The request contains invalid or missing parameters.

    **Common causes:**

    * Missing required fields
    * Invalid data types
    * Values outside allowed ranges
    * Invalid format (email, URL, UUID, etc.)
    * Business rule violations

    **How to fix:**

    * Check request body against API documentation
    * Validate data types and formats
    * Ensure all required fields are present
    * Review error details for specific field errors

    **Example:**

    ```json theme={null}
    {
      "success": false,
      "message": "Price must be greater than 0",
      "code": "ValidationError",
      "data": null
    }
    ```
  </Accordion>

  <Accordion title="BadCaptcha" icon="robot">
    **HTTP Status:** 400 Bad Request

    **Description:** CAPTCHA verification failed.

    **Common causes:**

    * Invalid CAPTCHA response
    * Expired CAPTCHA token
    * CAPTCHA not solved
    * Bot detection triggered

    **How to fix:**

    * Request new CAPTCHA challenge
    * Ensure user completes CAPTCHA
    * Check CAPTCHA token hasn't expired
    * Verify CAPTCHA integration is correct

    **Example:**

    ```json theme={null}
    {
      "success": false,
      "message": "CAPTCHA verification failed. Please try again.",
      "code": "BadCaptcha",
      "data": null
    }
    ```
  </Accordion>
</AccordionGroup>

### Resource Errors

<AccordionGroup>
  <Accordion title="NotFound" icon="magnifying-glass">
    **HTTP Status:** 404 Not Found

    **Description:** The requested resource does not exist.

    **Common causes:**

    * Invalid resource ID
    * Resource was deleted
    * Typo in endpoint URL
    * Resource belongs to different store

    **How to fix:**

    * Verify resource ID is correct
    * Check resource hasn't been deleted
    * Ensure you're querying the right store
    * Validate endpoint URL

    **Example:**

    ```json theme={null}
    {
      "success": false,
      "message": "Product not found",
      "code": "NotFound",
      "data": null
    }
    ```
  </Accordion>

  <Accordion title="ObjectConflict" icon="code-merge">
    **HTTP Status:** 409 Conflict

    **Description:** The operation conflicts with an existing resource.

    **Common causes:**

    * Duplicate unique field (email, slug, etc.)
    * Resource already exists
    * Concurrent modification conflict
    * Business rule prevents operation

    **How to fix:**

    * Use unique values for unique fields
    * Check if resource already exists
    * Implement optimistic locking for concurrent updates
    * Review business rules

    **Example:**

    ```json theme={null}
    {
      "success": false,
      "message": "A product with this slug already exists",
      "code": "ObjectConflict",
      "data": null
    }
    ```
  </Accordion>
</AccordionGroup>

### Rate Limiting

<AccordionGroup>
  <Accordion title="RateLimited" icon="gauge-high">
    **HTTP Status:** 429 Too Many Requests

    **Description:** You have exceeded the API rate limit.

    **Common causes:**

    * Too many requests in short time period
    * Burst limit exceeded
    * Account-level rate limit reached

    **How to fix:**

    * Implement exponential backoff
    * Respect `Retry-After` header
    * Cache frequently accessed data
    * Optimize API calls to reduce frequency
    * Contact support for higher limits

    **Response headers:**

    ```
    X-RateLimit-Limit: 100
    X-RateLimit-Remaining: 0
    X-RateLimit-Reset: 1638360000
    Retry-After: 60
    ```

    **Example:**

    ```json theme={null}
    {
      "success": false,
      "message": "Rate limit exceeded. Please retry after 60 seconds.",
      "code": "RateLimited",
      "data": null
    }
    ```
  </Accordion>
</AccordionGroup>

### Business Logic Errors

<AccordionGroup>
  <Accordion title="ProductUnavailable" icon="box">
    **HTTP Status:** 400 Bad Request

    **Description:** The requested product is not available for purchase.

    **Common causes:**

    * Product out of stock
    * Product is private or unlisted
    * Product deleted or disabled
    * Product not available in customer's region
    * Purchase limits exceeded

    **How to fix:**

    * Check product availability
    * Verify product stock levels
    * Ensure product is public
    * Check regional restrictions

    **Example:**

    ```json theme={null}
    {
      "success": false,
      "message": "This product is currently out of stock",
      "code": "ProductUnavailable",
      "data": null
    }
    ```
  </Accordion>

  <Accordion title="NotEnoughFunds" icon="wallet">
    **HTTP Status:** 400 Bad Request

    **Description:** Insufficient funds in customer balance.

    **Common causes:**

    * Customer balance too low
    * Attempting to use balance payment method
    * Withdrawal amount exceeds available balance

    **How to fix:**

    * Check customer balance
    * Request customer add funds
    * Use alternative payment method
    * Reduce order amount

    **Example:**

    ```json theme={null}
    {
      "success": false,
      "message": "Insufficient customer balance",
      "code": "NotEnoughFunds",
      "data": null
    }
    ```
  </Accordion>

  <Accordion title="VerificationRequired" icon="circle-check">
    **HTTP Status:** 403 Forbidden

    **Description:** Account verification is required before proceeding.

    **Common causes:**

    * Email not verified
    * Identity verification pending
    * Payment method requires verification
    * Account limits require verification

    **How to fix:**

    * Complete email verification
    * Submit required verification documents
    * Verify payment methods
    * Contact support for verification status

    **Example:**

    ```json theme={null}
    {
      "success": false,
      "message": "Email verification required",
      "code": "VerificationRequired",
      "data": null
    }
    ```
  </Accordion>
</AccordionGroup>

### Feature & Upgrade Errors

<AccordionGroup>
  <Accordion title="FeatureUnavailable" icon="lock">
    **HTTP Status:** 403 Forbidden

    **Description:** This feature is not available for your account.

    **Common causes:**

    * Feature disabled for your plan
    * Beta feature not enabled
    * Regional restrictions
    * Feature requires specific integration

    **How to fix:**

    * Check feature availability for your plan
    * Contact support to enable beta features
    * Verify regional availability
    * Review feature requirements

    **Example:**

    ```json theme={null}
    {
      "success": false,
      "message": "Advanced analytics is not available on your current plan",
      "code": "FeatureUnavailable",
      "data": null
    }
    ```
  </Accordion>

  <Accordion title="UpgradeRequired" icon="arrow-up">
    **HTTP Status:** 402 Payment Required

    **Description:** Your current plan does not support this operation.

    **Common causes:**

    * Plan limits exceeded
    * Feature requires higher plan tier
    * Usage quota exhausted

    **How to fix:**

    * Upgrade to higher plan tier
    * Review current plan limits
    * Reduce usage to stay within limits
    * Contact sales for enterprise options

    **Example:**

    ```json theme={null}
    {
      "success": false,
      "message": "You have reached the maximum number of products for your plan",
      "code": "UpgradeRequired",
      "data": null
    }
    ```
  </Accordion>

  <Accordion title="UnsupportedRequest" icon="circle-xmark">
    **HTTP Status:** 400 Bad Request

    **Description:** The requested operation is not supported.

    **Common causes:**

    * Deprecated API version
    * Invalid operation combination
    * Unsupported payment method
    * Unsupported currency

    **How to fix:**

    * Check API documentation for supported operations
    * Use current API version
    * Verify operation compatibility
    * Check supported payment methods/currencies

    **Example:**

    ```json theme={null}
    {
      "success": false,
      "message": "This payment method is not supported for subscriptions",
      "code": "UnsupportedRequest",
      "data": null
    }
    ```
  </Accordion>
</AccordionGroup>

### File & Upload Errors

<AccordionGroup>
  <Accordion title="UploadFailed" icon="cloud-arrow-up">
    **HTTP Status:** 400 Bad Request

    **Description:** File upload failed.

    **Common causes:**

    * File too large
    * Invalid file type
    * Corrupted file
    * Network interruption
    * Storage quota exceeded

    **How to fix:**

    * Check file size limits
    * Verify file type is supported
    * Ensure file is not corrupted
    * Retry upload with stable connection
    * Check storage quota

    **Example:**

    ```json theme={null}
    {
      "success": false,
      "message": "File size exceeds maximum allowed size",
      "code": "UploadFailed",
      "data": null
    }
    ```
  </Accordion>
</AccordionGroup>

### Server Errors

<AccordionGroup>
  <Accordion title="InternalServerError" icon="server">
    **HTTP Status:** 500 Internal Server Error

    **Description:** An unexpected error occurred on the server.

    **Common causes:**

    * Server-side bug
    * Database connection issue
    * External service failure
    * Unexpected condition

    **How to fix:**

    * Retry the request after a short delay
    * If problem persists, contact support
    * Check [status page](https://status.komerza.com) for incidents
    * Include error ID when contacting support

    **Example:**

    ```json theme={null}
    {
      "success": false,
      "message": "An unexpected error occurred",
      "code": "InternalServerError",
      "data": null
    }
    ```

    <Note>
      Always include the `errorId` when reporting issues to support for faster resolution.
    </Note>
  </Accordion>
</AccordionGroup>

## HTTP Status Code Summary

| Status Code | Error Codes                                                                                       | Description                                      |
| ----------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| 400         | ValidationError, BadCaptcha, ProductUnavailable, NotEnoughFunds, UnsupportedRequest, UploadFailed | Bad Request - Invalid input                      |
| 401         | BadToken, OAuthLoginRequired                                                                      | Unauthorized - Invalid or missing authentication |
| 402         | UpgradeRequired                                                                                   | Payment Required - Plan upgrade needed           |
| 403         | AccessDenied, TwoFactorRequired, VerificationRequired, FeatureUnavailable                         | Forbidden - Insufficient permissions             |
| 404         | NotFound                                                                                          | Not Found - Resource doesn't exist               |
| 409         | ObjectConflict                                                                                    | Conflict - Resource conflict                     |
| 429         | RateLimited                                                                                       | Too Many Requests - Rate limit exceeded          |
| 500         | InternalServerError                                                                               | Internal Server Error - Server-side issue        |

## Support Resources

<CardGroup cols={2}>
  <Card title="System Status" icon="wave-pulse" href="https://status.komerza.com">
    Check API and service status
  </Card>

  {" "}

  <Card title="Help Center" icon="messages-question" href="https://docs.komerza.com">
    Browse error troubleshooting guides
  </Card>

  {" "}

  <Card title="Discord Community" icon="discord" href="https://discord.gg/komerza">
    Get help from the community
  </Card>

  <Card title="Contact Support" icon="headset" href="https://dashboard.komerza.com/support">
    Report issues with error IDs
  </Card>
</CardGroup>