V3 Error Codes

When a V3 call fails, read the code field in the response body first. code = 0 means success; any other value is a fixed six-digit cloud error code, and it is independent of the HTTP status. This page lists the numbering rules, every defined code, and how to troubleshoot.

Unified error response

V3 business errors always return HTTP 200 OK, and the failure details are carried in the JSON envelope:

{
  "code": 210002,
  "msg": "Robot is offline.",
  "traceId": "35de92dd84f14097a383a323dee1e6e1",
  "data": {}
}

Field	Description
code	Cloud unified error code. Only 0 means success.
msg	Developer-facing English message for quick diagnosis. Do not branch on it in code.
traceId	Trace ID of this request. Include it when filing a ticket.
data	Business data. On failure it is always {} and carries no business field.

data is always an empty object on failure

A code != 0 response has no diagnostic fields such as data.cmdResultCode; the failure reason is only available from code and msg. Robot-side ten-digit error codes appear only in successful responses, see "Robot-side error codes and command status" below.

Do not judge success by the HTTP status code

Business failures also return 200, so you must parse code. Only gateway-level rejections (such as 401, 404, and 429) use a non-200 HTTP status.

Segments at a glance

Every V3 error code belongs to a business domain, so the leading digits tell you where the problem is:

Range	Domain	Typical scenarios
0	Success	The call succeeded
100000 ~ 109999	Common infrastructure	Internal error, downstream failure, invalid parameter, resource not found, rate limit, storage error
110000 ~ 119999	Authentication and security	Invalid internal token, missing or invalid credentials, no resource permission
210000 ~ 219999	Robot and device state	Robot not found, offline, or unsupported task or command
220000 ~ 229999	Map and space	Map not found, map resource not part of the map
230000 ~ 239999	Task scheduling and control	Combined task, schedule, and charging position validation and conflicts
800000 ~ 809999	Legacy adaptation layer	Converted from legacy API error codes
900000 ~ 909999	Legacy fallback	Legacy errors that cannot be mapped

Codes are not guaranteed to be contiguous inside a range; undefined numbers are not returned today.

Full code list

Common infrastructure (100000 ~ 100999)

Code	Meaning	Common cause
100000	Internal service error	Unclassified server error. Retry; if it persists, report it with the traceId
100001	Downstream call failed	Downstream timeout or response decoding failure
100003	Invalid parameter	Missing required field, wrong type, out-of-range enum, or too many items in one request
100025	Resource not found	The requested robot, map, or task does not exist or does not belong to your account
100026	Rate limit exceeded	Too many calls. Lower concurrency or increase the retry interval
100027	Data store error	Database read or write failure. Safe to retry

Authentication and security (110000 ~ 119999)

Code	Meaning	Common cause
110001	Invalid internal token	Service identity check failed in the internal forwarding chain; usually platform-side
110002	Missing or invalid credentials	Authorization missing, token expired, or malformed
110003	No resource permission	robotSn is not bound to your account, or belongs to another tenant
110004	Opaque token limit reached	10 valid tokens already exist; revoke unused ones first

Robot and device state (210000 ~ 219999)

Code	Meaning	Common cause
210000	Robot does not support the task or command	Model capability mismatch, or software version below AIO 1.6
210001	Robot not found or not in this cloud environment	Misspelled robotSn, or the robot is not bound to your account
210002	Robot is offline	An online-only command was sent while the robot was offline

Map and space (220000 ~ 229999)

Code	Meaning	Common cause
220001	Map not found, unbound, or expired	mapId is stale, or the map does not belong to that robot
220002	Map resource is not part of the map	The partition, path, or position does not match the supplied map

Task scheduling and control (230000 ~ 239999)

Code	Meaning
230001	Schedule robot not found or not permitted
230002	Schedule plan not found or already deleted
230003	Robot Columbus routing information is empty; cannot dispatch yet
230004	Schedule map resource (partition, path, or position) not found
230005	Work mode cannot be matched uniquely
230006	Invalid schedule execution type; only 1 (time-based) or 2 (quantity-based)
230007	The simple API received an advanced configuration field that is not open
230008	The robot's current site does not exist
230009	Map not found or not part of the current site
230010	mapId is not the localMapUuid, or the two differ
230011	Invalid schedule date format or range
230012	Invalid schedule time format or range
230013	Schedule start date is earlier than today
230014	Task runtime or task item not found
230015	Task state does not allow this command, or the task version conflicts
230016	Combined task definition not found or already deleted
230018	The charging position does not exist or is not part of the requested map
230019	The map has multiple charging positions but the request did not choose one
230020	The map has no available charging position
230021	The requested map does not exist or its name cannot be resolved

Schedule and charging position details

230001 ~ 230013 mostly come from schedule APIs. Query task resources first to confirm partitions, paths, and positions before building the request. 230018 ~ 230021 come from charging position APIs; call the charging position list first to obtain a valid identifier.

Legacy adaptation layer (800000 ~ 809999)

When you call legacy APIs or a private-cloud backend, old error codes are converted into the 8xxxxx range automatically. An 8xxxxx code means the error came from the legacy adaptation layer, and its message comes from the original downstream API. Troubleshoot it against that API's own error definition rather than reading it as a V3 segment.

The conversion rules are an internal platform implementation, are not documented here, and are not part of the public contract. When a downstream returns a standard gRPC status code, the adaptation layer normalizes it into the corresponding V3 code, so you can handle it as a V3 code.

Legacy fallback (900000 ~ 909999)

Code	Meaning
900001	A legacy error that cannot be mapped. Report it with the traceId.

Robot-side codes and command status

The 10-digit error codes returned by the robot are never placed in the outer code field. They appear inside data of successful responses (code = 0):

Field	Description
data.cmdStatus	Command status. 6 means dispatched successfully, 7 means the robot-side execution failed.
data.cmdResultCode	The robot-side 10-digit decimal error code, preserved as a string.
data.cmdResultMessage	English description of that code; an empty string when the cache misses.

A command that reached the robot but failed on the robot side is still a successful response. In that case code = 0 and data.cmdStatus = 7, and the failure reason is read from data.cmdResultCode. Only when the cloud itself rejects the request (invalid parameter, robot offline, no access) does the response return code != 0, and then data is an empty object with no robot-side code. Always check code first, then decide whether to parse data.cmdResultCode.

Three command status cases are easy to misread:

• When cmdStatus = 6, the response always carries cmdResultCode = 6880 and cmdResultMessage = success. This only means the command was dispatched successfully, not that the robot finished the action. Query the task or robot state to confirm the outcome.
• When cmdStatus = 7, cmdResultCode carries the real failure reason and must be read against the robot-side error code table.
• For any other cmdStatus, cmdResultCode may be empty because no execution result exists yet. Query the command status again.

Task startup failures (10-digit codes such as 20101000xx) are robot-side business codes. Look them up in "Task Startup Failure Error Codes" and do not confuse them with the six-digit cloud codes.

HTTP status versus business codes

When the gateway rejects a request before it reaches the business route, it uses a standard HTTP status and the response may have no V3 envelope:

HTTP status	Meaning	Action
400	Malformed request body or missing mandatory header	Check for truncated JSON and the Content-Type header
401	Token missing or signature check failed	Obtain a new access_token
403	Identity is valid but the API is not permitted	Review the account role and API permissions
404	Route not found	Check the URL; V3 business APIs start with /openapi/v3/
429	Rate limited	Lower concurrency and retry with backoff
500 / 502 / 504	Gateway error or backend unreachable	Retry later; report with the traceId if it persists

Troubleshooting order

1. Read code, not the HTTP status. HTTP 200 can still be a business failure.
2. Locate the domain by range. 1xxxxx is platform and authentication, 2xxxxx is robot and business, 8xxxxx / 9xxxxx is the legacy adaptation layer.
3. For 110003, check the binding first. Most "no permission" errors mean robotSn is not bound to your account, not that the token is broken.
4. For 100003, compare against the field reference. Focus on required fields, enum ranges, per-request limits, and array item structure.
5. Wait for async commands. code = 0 only means the request was accepted; use requestId to query command status or records.
6. Include traceId in reports. It links the cloud logs to your exact request.

Related pages: List Robots, Get Robot Status Snapshot, Get Command Status, List Command Records, and Task Startup Failure Error Codes.