Error responses

Understand InnoPaaS API error responses, codes, and retry guidance.

Every InnoPaaS API returns the same JSON error envelope. Use the six-digit code to decide what happened and what to do next.

HTTP status is a coarse signal. A 2xx response can still contain a non-success business code, so always inspect the response body.

Response envelope

{
  "code": "010003",
  "message": "The value of 'to' is invalid. Use an E.164 number such as +6581234567.",
  "data": null,
  "traceId"

Last updated on

Field	Type	Description
`code`	string	Required. Six-character numeric string; `000000` means success.
`message`	string	Required. Human-readable explanation. Do not use it for program logic.
`data`	object, array, or null	Required. Business result; `null` when the whole request fails.
`traceId`	string	Required. Correlation ID for support and internal log lookup.
`timestamp`	string	Required. Response time in UTC ISO 8601 with milliseconds and a `Z` suffix.

Situation	Recommended action
A request, credential, permission, balance, or configuration is wrong	Fix the cause, then submit a new request.
A rate limit or temporary outage has a reliable recovery window	Wait for `Retry-After` when present; otherwise use bounded exponential backoff.
The original request may have been accepted	Check the original request before resending; reuse the same idempotency key and content when supported.
The message was rejected or delivery failed	Do not automatically resend. A new send is a new business operation and may create another charge.
The code is not documented	Log `code`, `message`, and `traceId`; stop automatic retries and contact support.

Range	Area	Coverage
`000000`	Success	The API operation succeeded.
`01xxxx`	Request and resource	Parameters, formats, resources, state, and idempotency conflicts.
`02xxxx`	Identity and access	API Key, permissions, IP, account, activation, and authentication.
`03xxxx`	Billing and quota	Balance, credit, period quota, and billing configuration.
`04xxxx`	Rate and concurrency	Request rate, sending rate, and concurrency.
`05xxxx`	Platform service	Internal errors, unavailability, and uncertain results.
`06xxxx`—`09xxxx`	General reserved	Assigned centrally after application.
`202xxx`	SMS	SMS submission rules and delivery results.
`11xxxx`	WhatsApp	Product-specific errors; codes to be defined separately.
`12xxxx`	Voice	Product-specific errors; codes to be defined separately.
`13xxxx`	Wanshu	Product-specific errors; codes to be defined separately.
`14xxxx`	Email
`15xxxx`	rcs/mms
`16xxxx`
`14xxxx`—`89xxxx`	Future product reserved	Allocated by product line.
`90xxxx`—`99xxxx`	Not allocated	Reserved for expansion.

Code range	HTTP status
`010001`–`010003`, `010011`–`010013`	`400`
`010004`	`413`
`010005`	`404`
`010006`–`010008`	`409`
`010009`	`405`
`010010`	`415`
`020001`, `020002`, `020008`, `020009`	`401`
`020003`–`020007`	`403`
`030001`, `030002`	`402`
`030003`, `030004`	`403`
`030005`	`503`
`040001`–`040003`	`429` with `Retry-After`
`050001`	`500`
`050002`	`503`
`050003`	`504`
`100001`–`100010`	`422`
`100011`	`503`
`101xxx`	Not an HTTP error on the send request; see the query result or event data