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": "d87a93e50af0437ebcc0c80774126842",
"timestamp": "2026-10-21T03:00:01.000Z"
}| 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. |
How to handle errors
| 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. |
A successful send request only means the request was accepted; it is not proof that the message was delivered.
Error catalog
| 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 | 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 | ||
15xxxx | rcs/mms | |
16xxxx | ||
14xxxx—89xxxx | Future product reserved | Allocated by product line. |
90xxxx—99xxxx | Not allocated | Reserved for expansion. |
Target HTTP status mapping
This table is the target mapping. The current SMS submit API still returns HTTP 200 for business errors; use the response body code. The actual status of an endpoint is defined by its API reference until the migration is complete.
| 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 |
Related
Last updated on