Error Code Reference

Response Format

All API responses use a unified JSON envelope format:

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

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

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

Check the code field

A response code of 0 indicates success. For non-zero values, check the message field for the error description.

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

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.

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.

Overview

Platform API

Authentication & Keys

Integrations

SDK

Cookbook

Reference

Error Code Reference

Response Format

HTTP Status Codes

Business Error Code Reference

Authentication & Security

Files & Storage

Credits & Consumption

Recharge

Subscriptions & Plans

Payments

Gift Cards

Invoices

Skills & Applications

Tasks

Infrastructure

Error Handling Recommendations

​Response Format

​HTTP Status Codes

​Business Error Code Reference

​Authentication & Security

​Files & Storage

​Credits & Consumption

​Recharge

​Subscriptions & Plans

​Payments

​Gift Cards

​Invoices

​Skills & Applications

​Tasks

​Infrastructure

​Error Handling Recommendations

Response Format

HTTP Status Codes

Business Error Code Reference

Authentication & Security

Files & Storage

Credits & Consumption

Recharge

Subscriptions & Plans

Payments

Gift Cards

Invoices

Skills & Applications

Tasks

Infrastructure

Error Handling Recommendations