Error Codes & Rate Limiting

Standard Response Structure

Both success and failure responses share a unified JSON envelope (business field names remain in English):

{
  "code": 0,
  "message": "success",
  "data": {},
  "timestamp": 1700000000
}

• code: Business error code; 0 means success. AI / automated integrations should branch on code — do not rely on the natural-language message text.
• message: Human-readable description.
• data: Payload on success; typically null or an agreed-upon structure on failure.
• timestamp: Unix timestamp (seconds).

Error Code Table (by Range)

1xxx — General

code	Semantic Constant (Example)	Description
1001	ParamError	Invalid parameter
1002	AuthenticationError	Authentication failed
1003	PermissionDenied	Insufficient permissions
1004	NotFound	Resource not found
1005	AlreadyExists	Resource already exists
1006	APIKeyInvalid	Invalid API Key
1007	UserNotInPlatform	User not on the platform or not bound
1008	ValidationError	Validation failed

2xxx — Authentication / Login

code	Semantic Constant (Example)	Description
2001	VerificationCode	Verification code related error
2002	CodeRateLimit	Verification code / SMS rate limit
2003	WrongPassword	Incorrect password

3xxx — Wallet

code	Semantic Constant (Example)	Description
3001	InsufficientBalance	Insufficient balance
3002	WalletOperation	Wallet operation failed
3003	WithdrawInsufficient	Insufficient withdrawable balance, etc.
3004	TaskDrafted	Related to draft task / fund pre-authorization rejection

4xxx — Business / Tasks / Orders

code	Semantic Constant (Example)	Description
4001	TaskStatus	Task status does not permit this operation
4091	TaskAlreadyClaimed	Task already claimed / conflict state
4501	OrderStatus	Order status does not permit this operation
4502	OrderTimeout	Order timed out

5xxx — AI

code	Semantic Constant (Example)	Description
5001	AIServiceError	Downstream AI service error or unavailable

7xxx — Invitations

code	Description
7001	Invitation business error (e.g., invalid invitation code)
7002	Invitation expired
7003	Invitation already used
7004	Invitation quota reached / limit exceeded
7005	Self-invitation not allowed or other rule rejection
7006	Invitation record not found

8xxx — Recharge

code	Description
8001	Recharge creation or channel failure
8002	Recharge processing / pending payment
8003	Invalid recharge amount
8004	Recharge order not found
8005	Recharge status conflict

9999 — System

code	Description
9999	Uncategorized internal error / system exception

The exact code and HTTP status combinations are authoritative in the live openapi.json and API documentation. The table above is intended for quick triage during integration.

HTTP Status Code Mapping (Conventions)

HTTP	Meaning	Integration Guidance
400	Client request error	Fix parameters — do not blindly retry
401	Unauthenticated / token expired	Refresh login or replace Key
403	Forbidden	Check role and resource ownership
404	Resource not found	Fix the id or sync state
409	Conflict (state, concurrency)	Fetch latest state before deciding
422	Semantic validation failed	Fix the body per the schema
429	Rate limited	Read Retry-After, back off, then retry
500 / 502	Server or gateway error	Limited retries with backoff

Rate Limiting

Dimension	Rule
Global rate limit	60 requests / minute (may be enforced per IP or by gateway policy; check actual response headers)
demo-search	10 requests / minute (IP-based)

When rate-limited, the platform returns 429 with a Retry-After header (in seconds). Clients and AI Agents should use exponential backoff and respect this header.

Idempotency

• For write operations (create, update, payment, withdrawal, etc.), it is recommended to always include the request header: Idempotency-Key (unique, ideally non-repeating within 24 hours).
• The platform returns the same business result for duplicate requests with the same Idempotency-Key, preventing automatic retries from causing duplicate charges or duplicate orders.

For more client-side patterns, see Best Practices.