惯例

请求格式

请求需要使用 HTTP 头 'Content-Type'，其值为 'application/json'。此外，所有经过身份验证的端点都需要标准的 Bearer 授权头和有效的令牌。

  Content-Type: application/json
  Authorization: Bearer 8s2wfclhyp5iiikowm3ocnfalt7qfl7es8xhuda3ttusslssx6c14hq7yocp62c5

POST 请求的参数预期为 JSON 对象，包含在请求体中。

响应格式

响应以 JSON 对象形式返回，包含以下常见字段：

字段	描述
response: json	表示响应的 JSON 数据。根据具体请求的不同，可以是标量、数组或对象。
error: short-string	简短的错误 "枚举"，如 "not_found", "invalid_resource", "invalid_password"。
error_description: long-string	附加的错误信息。
messages: {"field1":["problem1","problem2"],...}	数据验证问题，特别是在 422 响应中。

请求参数

设备/实体/车辆端点的路径参数 {vehicle_tag} 预期为从列表端点返回的记录的整数 ID。例如：车辆列表。对于车辆端点和车辆指令，可以使用有效的 VIN 代替整数 ID。

响应代码

端点示例中未涵盖所有可能的响应代码。以下是常见的状态代码含义。响应体通常以 JSON 编码，详细信息在 "error" 字段中。

成功

状态码	描述	细节
200	Ok	请求处理成功。
201	Created	记录创建成功。

客户端错误

状态码	描述	细节
400	Bad Request
		• invalid_command - 数据请求或命令未知。
		• invalid_field - 输入中的字段无效。
		• invalid_request - 请求体无效，可能返回具体的错误消息描述。
		• invalid_auth_code - 请求体中的 "code" 无效，请生成新的并重试。
		• invalid_redirect_url - 无效的重定向 URI/URL。授权重定向 URI 和令牌重定向 URI 必须匹配。
		• unsupported_grant_type - 授权类型无效。请使用其中之一：client_credentials、refresh_token、authorization_code。
		• unauthorized_client - 我们不识别此 client_id 和 client_secret 的组合。请使用已为应用程序授予的 client_id 和 client_secret。
401	Unauthorized
		• mobile_access_disabled - 车辆已关闭远程访问。
		• 无响应体 - OAuth 令牌已过期。
		• login_required - 用户已重置密码，需要新的授权码；refresh_token 已使用过；或用户已撤销应用程序访问权限。
402	Payment Required	需要付费才能使用 API（仅限非免费账户）。
403	Forbidden
		• 没有授权访问此资源，开发者应检查所需的范围。
		• 要与设备进行交互，需要特斯拉车辆指令协议。
404	Not Found	请求的资源不存在。
405	Not Allowed	操作不允许。
406	Not Acceptable	HTTP 请求的 Content-Type 头未设置为 `application/json`。
408	Device Not Available	如果请求时车辆不处于 "在线" 状态。
412	Precondition Failed	未满足处理请求所需的条件。
		• 未注册帐户 - 首先调用合作伙伴帐户注册端点。
418	Client Too Old (Not supported)	移动应用程序需要更新（仅适用于特斯拉应用）。
421	Incorrect region	用户不在当前地区。详见区域要求部分获取更多信息。
422	Invalid Resource	数据存在语义问题，例如缺失或无效数据。
		• 车辆尚不支持Tesla车辆指令协议。
423	Locked	帐户被锁定，需要由特斯拉解锁。无响应体。
429	Rate limited	帐户或服务器受到限速。当帐户发出过多请求时会发生此情况。
		• 检查请求头 'RateLimit-Reset' 或 'Retry-After'，以确定何时发出下一个请求。
451	Resource Unavailable For Legal Reasons	未经正确隐私设置查询用户/车辆（例如，错误的地区）。
499	Client Closed Request	客户端在服务器能够发送响应之前关闭了请求。

服务器错误

状态码	描述	细节
500	Internal server error	处理请求时发生错误。
503	Service Unavailable	内部服务或车辆未响应（超时）。
504	Gateway Timeout	服务器未收到响应。

设备错误

状态码	描述	细节
540	Device Unexpected response	车辆响应错误 - 可能需要重启、OTA 更新或维护。

API 状态

GET /status

curl ' https://fleet-api.prd.cn.vn.cloud.tesla.cn/status'

此端点如果 API 正常运行，则返回字符串 "ok"。不需要 HTTP 头。