Integration Guide

Request entry point

The Server API entry point is https://{gateway_host}. Use HTTPS and configure reasonable connection, read, and overall timeouts on the server.

Unified response

Most open APIs use the following response envelope:

{ "code": 200, "msg": "", "data": {} }

code=200 indicates success and code=500 indicates a business failure. Authentication failures use HTTP status codes, such as 401 INVALID_TOKEN and 403 SCOPE_DENIED. The OAuth token and UserInfo APIs use an OAuth JSON envelope; see Authentication and signing.

Common request rules

• Put the token in Authorization: Bearer, the query string, or the form as specified by each API; use only one method per request.
• A request body with Content-Type: application/json must contain valid JSON.
• Send member IDs, department IDs, and robot IDs as strings.
• Do not write code or access_token to logs, URLs, analytics, or error reports.

Errors and retries

Type	Handling
400 parameter error	Correct the request; do not retry.
401 invalid token	Obtain a new token and retry once.
403 permission or IP restriction	Check the permission configuration; do not retry.
5xx or network timeout	Use bounded exponential backoff and a circuit breaker.
Robot business failure	Decide whether to retry based on item-level errors and the idempotency key.

Query APIs are naturally idempotent. The app must guarantee idempotency for robot sending APIs and event callbacks.

Error codes and rate limits

Robot APIs can fail at the HTTP layer, request-level business layer, or individual delivery layer.

Layer	Typical errors	Handling
HTTP	401 INVALID_TOKEN, 403 SCOPE_DENIED, 503	Fix authentication or use bounded backoff.
Request-level	INVALID_REQUEST, PERMISSION_DENIED	Correct the request; do not retry invalid parameters.
Item-level result	rejected, failed	Handle results by user and error code.

Retry rules

• Sending APIs must set Idempotency-Key; keep the same key and request body when retrying.
• Network timeouts and 5xx responses may use exponential backoff; do not automatically retry 4xx parameter, permission, or visibility-scope errors.
• Split batch requests according to business volume to avoid contacting too many members at once.
• Record the request ID, target count, and result summary, but never record tokens, secrets, or complete private content.

Platform rate-limit policies may change. Callers should cache access_token, control concurrency, and back off after receiving a rate-limit response or 503.