Docs MenuTap to expand ▼

Home Open Platform DocsError Codes

Error Codes

Awice Logistics Open Platform uses 4-digit error codes grouped by leading digit. Every error response includes a request_id, which speeds up triage when you file a ticket.

Error Response Structure

{
  "code": 2002,
  "msg": "Signature verification failed",
  "detail": "expected signature does not match",
  "request_id": "f8a92c1e-3b4d-4f1a-b3a7-9c2e1f6d8b3a"
}

Billing Rules

Only code = 0 (success) deducts credits
HTTP 4xx / 5xx never deduct credits
Business failures (e.g. port not found, no results) return HTTP 200 with code ≠ 0 and do not deduct credits
Client-side timeouts (no response in 10s) do not deduct credits

Success

Business call succeeded; credits are deducted.

code	HTTP	Meaning	Client Action
0	200	Success	Process the data normally

1xxx Parameter Errors

Bad request parameters; no credits deducted.

code	HTTP	Meaning	Client Action
1001	400	Missing parameter / invalid type	Check required fields, types, and length limits
1002	400	Multiple matches (ambiguous) for carrier/airline	Pick a specific code from the candidates field and resend. Note: pol/pod port matches no longer return this code — rates for all matched ports are returned automatically
1003	400	Parameter out of allowed range	Check boundaries for page/limit/weight
1004	400	Conflicting combined parameters	Review the API doc for mutually exclusive fields

2xxx Authentication Errors

Auth failure; no credits deducted. Alert instead of retrying.

code	HTTP	Meaning	Client Action
2001	401	AppKey does not exist or has been revoked	Do not retry. Check app status in the console
2002	401	Signature verification failed	Compare with the Auth doc (METHOD/PATH/JSON whitespace)
2003	401	Timestamp expired (> ±300s)	Sync system NTP time
2004	401	Nonce reused (already used within 10 minutes)	Regenerate nonce and retry once
2005	401	Request IP not in whitelist	Add the IP in Console → App Management
2006	401	Missing X-Awice-* headers	Verify all 4 required headers are present

3xxx Billing Errors

Plan / balance issues; no credits deducted. Alert the user directly.

code	HTTP	Meaning	Client Action
3001	402	Insufficient credits (balance used up, or free trial pack not claimed yet)	Do not retry. Claim the trial pack or buy a plan in the console. The response carries trial_available so you can branch programmatically
3003	402	Dictionary search requires an active plan (not open to accounts without a subscription)	Claim the trial pack or buy a plan; for dropdown options use dict/popular instead (free, unlimited)
3004	402	Plan expired (response carries expired_at / frozen_credit)	Renew or buy a new plan. Note: credits left unused when a plan expires are forfeited

4xxx Rate Limiting

QPS exceeded; no credits deducted. The Retry-After header indicates when to retry.

code	HTTP	Meaning	Client Action
4001	429	QPS limit exceeded	Exponential backoff retry; honor the Retry-After header
4002	429	Daily call count exceeded soft limit	Recover after 24h or contact sales to raise the limit

5xxx Server Errors

Server-side issue; no credits deducted. Retry 1-2 times.

code	HTTP	Meaning	Client Action
5001	500	Internal server error	Retry once; if still failing, file a ticket with request_id
5002	503	Upstream service unavailable (express endpoint only)	Retry up to 2 times at 2s intervals
5003	504	Upstream response timed out	Increase client timeout and retry

Recommended Retry Strategy

code range	Retry?	Recommended strategy
1xxx	Do not retry	Param errors — retrying won't help. Alert and investigate manually.
2xxx	Do not retry	Auth issue (only 2004 nonce can be retried once)
3xxx	Do not retry	Plan issue — alert operations
4xxx	Retryable	Exponential backoff: 1s / 2s / 4s, honor Retry-After
5xxx	Retryable	Up to 2 retries, 1-3s interval; file a ticket with request_id

Next: Ocean FCL Rate Query

Error Codes - Awice Logistics Open Platform Docs | 5688.cn