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

# Error Code Reference

> Complete reference for Profy API HTTP status codes and business error codes

## Response Format

All API responses use a unified JSON envelope format:

```json theme={null}
{
  "code": 0,
  "message": "success",
  "data": { ... }
}
```

| Field     | Description                                                                     |
| --------- | ------------------------------------------------------------------------------- |
| `code`    | Business error code. `0` indicates success; non-zero indicates a specific error |
| `message` | Human-readable error description                                                |
| `data`    | Business data on success; `null` on failure                                     |

## HTTP Status Codes

HTTP status codes and business error codes are two separate dimensions. Profy's mapping rules:

| HTTP Status | Meaning               | Typical Scenario                                        |
| ----------- | --------------------- | ------------------------------------------------------- |
| `200`       | Success               | Normal business response                                |
| `400`       | Bad Request           | Parameter validation failure, invalid operation         |
| `401`       | Unauthorized          | Token expired or invalid                                |
| `403`       | Forbidden             | Account disabled, insufficient balance, quota exhausted |
| `404`       | Not Found             | Resource does not exist                                 |
| `409`       | Conflict              | Duplicate operation (e.g., order already paid)          |
| `429`       | Too Many Requests     | Rate limit triggered                                    |
| `500`       | Internal Server Error | Internal exception                                      |
| `503`       | Service Unavailable   | Service temporarily unavailable                         |

<Note>
  5-digit business codes (e.g., `40004`) are mapped to their corresponding HTTP status code range by the first digit: `4xxxx` → `400`, `5xxxx` → `500`.
</Note>

## Business Error Code Reference

### Authentication & Security

| Error Code | Name                  | Description                               |
| ---------- | --------------------- | ----------------------------------------- |
| `400`      | `CODE_INVALID`        | Verification code is incorrect or expired |
| `403`      | `ACCOUNT_DISABLED`    | Account has been disabled                 |
| `400`      | `CAPTCHA_FAILED`      | CAPTCHA verification failed               |
| `429`      | `SMS_TOO_FREQUENT`    | Verification codes sent too frequently    |
| `500`      | `SMS_SEND_FAILED`     | SMS delivery failed                       |
| `401`      | `AGENT_TOKEN_INVALID` | Agent Token is invalid                    |

### Files & Storage

| Error Code | Name                     | Description                                            |
| ---------- | ------------------------ | ------------------------------------------------------ |
| `404`      | `FILE_NOT_FOUND`         | File does not exist                                    |
| `500`      | `FILE_UPLOAD_FAILED`     | File upload failed                                     |
| `500`      | `FILE_DOWNLOAD_FAILED`   | File download failed                                   |
| `400`      | `FILE_TYPE_NOT_ALLOWED`  | File type not allowed for upload                       |
| `400`      | `FILE_TYPE_MISMATCH`     | File type does not match its extension                 |
| `400`      | `FILE_SIZE_EXCEEDED`     | File size exceeds the limit                            |
| `403`      | `STORAGE_QUOTA_EXCEEDED` | Cloud storage quota exceeded; please upgrade your plan |

### Credits & Consumption

| Error Code | Name                           | Description                                   |
| ---------- | ------------------------------ | --------------------------------------------- |
| `400`      | `CONSUME_TYPE_INVALID`         | Invalid consumption type                      |
| `400`      | `CONSUME_PARAM_MISSING`        | Missing consumption parameters                |
| `400`      | `CONSUME_MODEL_RATE_ZERO`      | This model does not support this billing mode |
| `400`      | `CONSUME_BALANCE_INSUFFICIENT` | Insufficient credits; please recharge         |
| `400`      | `CONSUME_BALANCE_OVERDRAFT`    | Credit account is overdrawn                   |
| `500`      | `CONSUME_DEDUCT_FAILED`        | Credit deduction failed                       |
| `403`      | `CONSUME_ORG_QUOTA_EXCEEDED`   | Monthly team quota has been used up           |
| `403`      | `CREDIT_ACCOUNT_FROZEN`        | Credit account has been frozen                |
| `400`      | `CREDIT_BALANCE_INSUFFICIENT`  | Insufficient credits                          |

### Recharge

| Error Code | Name                                  | Description                                                     |
| ---------- | ------------------------------------- | --------------------------------------------------------------- |
| `400`      | `RECHARGE_PLAN_NOT_FOUND`             | Recharge plan does not exist                                    |
| `500`      | `RECHARGE_PLANS_NOT_CONFIGURED`       | Recharge plans not configured                                   |
| `400`      | `RECHARGE_AMOUNT_INVALID`             | Recharge amount is out of the allowed range                     |
| `400`      | `RECHARGE_PARAM_CONFLICT`             | Only one of `planId` or `customAmount` can be provided          |
| `429`      | `RECHARGE_TOO_MANY_PENDING`           | Too many pending recharge orders                                |
| `403`      | `RECHARGE_REQUIRES_PAID_SUBSCRIPTION` | A paid subscription is required before purchasing a top-up pack |
| `403`      | `RECHARGE_TEAM_ADMIN_ONLY`            | Team credits can only be recharged by an administrator          |

### Subscriptions & Plans

| Error Code | Name                            | Description                                                |
| ---------- | ------------------------------- | ---------------------------------------------------------- |
| `404`      | `SUBSCRIPTION_NOT_FOUND`        | No active subscription found                               |
| `400`      | `SUBSCRIPTION_INVALID_PLAN`     | Invalid plan code                                          |
| `400`      | `SUBSCRIPTION_CANNOT_DOWNGRADE` | Plan downgrade is not supported                            |
| `400`      | `SUBSCRIPTION_ALREADY_ACTIVE`   | An active plan already exists; please use the upgrade flow |
| `400`      | `TEAM_ALREADY_IN_ORG`           | Already a member of a team; cannot create a duplicate      |
| `400`      | `TEAM_SUBJECT_UNAVAILABLE`      | Cannot switch to team; please join or subscribe first      |
| `403`      | `TEAM_LICENSE_EXPIRED`          | Team plan has expired                                      |

### Payments

| Error Code | Name                        | Description                                   |
| ---------- | --------------------------- | --------------------------------------------- |
| `404`      | `PAY_ORDER_NOT_FOUND`       | Payment order does not exist                  |
| `400`      | `PAY_ORDER_EXPIRED`         | Payment order has expired                     |
| `400`      | `PAY_ORDER_ALREADY_PAID`    | Order has already been paid; do not pay again |
| `500`      | `PAY_CREATE_FAILED`         | Failed to create payment order                |
| `400`      | `PAY_CHANNEL_NOT_SUPPORTED` | Payment channel not supported                 |

### Gift Cards

| Error Code | Name                              | Description                                 |
| ---------- | --------------------------------- | ------------------------------------------- |
| `40004`    | `GIFT_CARD_CODE_NOT_FOUND`        | Card code does not exist                    |
| `40005`    | `GIFT_CARD_CODE_INVALID`          | Card code is invalid                        |
| `40006`    | `GIFT_CARD_CODE_ALREADY_REDEEMED` | Card code has already been redeemed         |
| `40007`    | `GIFT_CARD_CODE_EXPIRED`          | Card code has expired                       |
| `40008`    | `GIFT_CARD_CODE_FROZEN`           | Card is flagged; please contact support     |
| `40010`    | `GIFT_CARD_BATCH_EXHAUSTED`       | All cards in this batch have been claimed   |
| `40011`    | `GIFT_CARD_BATCH_CLAIM_LIMIT`     | Claim limit for this batch has been reached |

### Invoices

| Error Code | Name                         | Description                                          |
| ---------- | ---------------------------- | ---------------------------------------------------- |
| `400`      | `INVOICE_ORDER_NOT_PAID`     | This order has not been paid yet                     |
| `400`      | `INVOICE_ORDER_EXPIRED`      | The 60-day invoicing period has passed               |
| `400`      | `INVOICE_ALREADY_EXISTS`     | An invoice has already been requested for this order |
| `400`      | `INVOICE_PROFILE_INCOMPLETE` | Please complete your invoice information first       |
| `400`      | `INVOICE_CANCEL_NOT_ALLOWED` | Only pending invoices can be cancelled               |

### Skills & Applications

| Error Code | Name                | Description                           |
| ---------- | ------------------- | ------------------------------------- |
| `404`      | `SKILL_NOT_FOUND`   | Skill does not exist                  |
| `400`      | `SKILL_OFFLINE`     | Skill has been taken offline          |
| `404`      | `APP_NOT_FOUND`     | Associated application does not exist |
| `404`      | `API_KEY_NOT_FOUND` | API Key does not exist                |

### Tasks

| Error Code | Name                     | Description                                                  |
| ---------- | ------------------------ | ------------------------------------------------------------ |
| `404`      | `TASK_NOT_FOUND`         | Task does not exist                                          |
| `403`      | `TASK_ACCESS_DENIED`     | No permission to access this task                            |
| `400`      | `TASK_ALREADY_SUBMITTED` | Task has already been submitted; cannot repeat the operation |
| `400`      | `TASK_INPUT_EMPTY`       | At least one input parameter is required                     |
| `409`      | `TASK_ALREADY_PAID`      | Task has already been paid                                   |
| `400`      | `TASK_PAY_INSUFFICIENT`  | Insufficient credits to pay for this task                    |

### Infrastructure

| Error Code | Name                         | Description                          |
| ---------- | ---------------------------- | ------------------------------------ |
| `503`      | `SERVICE_UNAVAILABLE`        | Service is temporarily unavailable   |
| `500`      | `SMS_CLIENT_INIT_FAILED`     | SMS client initialization failed     |
| `500`      | `CAPTCHA_CLIENT_INIT_FAILED` | CAPTCHA client initialization failed |

## Error Handling Recommendations

<Steps>
  <Step title="Check the code field">
    A response `code` of `0` indicates success. For non-zero values, check the `message` field for the error description.
  </Step>

  <Step title="Handle HTTP status codes">
    * `401`: Refresh the token or re-authenticate
    * `429`: Add backoff-and-retry logic
    * `5xx`: Server-side error; retry after a delay
  </Step>

  <Step title="Branch on error names">
    Use error names (e.g., `CONSUME_BALANCE_INSUFFICIENT`) rather than numeric error codes for conditional branching in your code to improve readability.
  </Step>
</Steps>

<Warning>
  Do not rely on the `message` field for programmatic logic — error messages may be reworded across versions. Always use the numeric `code` or the error name.
</Warning>