400
invalid_request修正 JSON body 后再发送，不要原样重复请求。
API
Tool Agent API
让你的 Agent、自动化脚本或内部工作流通过 API key 调用 Ecomwith 工具。当前文档覆盖 GTIN、QR Code、UTM Builder 和 Break-even ROAS API。
认证
在设置页创建 API key。完整密钥只显示一次，请复制到你的 Agent 或密钥管理器，之后页面只会显示脱敏后的 key。
Authorization: Bearer ecw_live_...
X-API-Key: ecw_live_...额度与限速
API 调用有独立用量记录。成功和限额响应会提供 quota.remaining 与 rateLimit.remaining（以及对应的 X-* headers）；分钟限速按 UTC 整分钟窗口，并按每个 API key + 工具分别计数。超过每分钟上限会返回 429 rate_limited，请按 Retry-After 等待后再试。
X-Quota-Limit: 1000
X-Quota-Remaining: 997
X-RateLimit-Limit: 30安全重试
网络超时或 Agent 自动重试时，使用同一个 Idempotency-Key。相同 key 与相同请求体会复用结果；换请求体会返回 idempotency_conflict，仍在处理时会返回 idempotency_in_progress。
Idempotency-Key: order-sync-2026-06-14-001按 scope 授权
每个 API key 只选择实际需要的工具 scope，例如 tools:gtin:generate。scope 只限制工具，不会提升会员等级、额度或限速。
Scope: tools:gtin:generateAPI key 安全
完整 API key 只显示一次。请保存到环境变量或密钥管理器，不要写入代码、URL、日志、截图或聊天记录；怀疑泄露时立即删除并重新创建。
ECOMWITH_API_KEY=ecw_live_...错误与处理
错误响应使用 error.code 和 error.message。先按状态码和错误码处理，再决定是否等待或用同一个 Idempotency-Key 重试。
401
authentication_required / invalid_api_key检查 Authorization: Bearer 或 X-API-Key；不要把完整 key 写进错误日志。
403
membership_required / insufficient_scope检查当前套餐和 key 的 scope；scope 不能提升会员额度。
409
idempotency_conflict / idempotency_in_progress同一业务请求保持同一个 key；冲突先停止，处理中等待后用同 key 重试。
413
payload_too_large缩小请求体到当前套餐的 payload 限制以内，再重新发送。
429
quota_exceeded / rate_limited / concurrency_limited读取 X-Quota-*、X-RateLimit-* 和 Retry-After；额度为 0 时停止，限速或并发时等待。
| 状态 | error.code | 下一步 |
|---|---|---|
| 400 | invalid_request | 修正 JSON body 后再发送，不要原样重复请求。 |
| 401 | authentication_required / invalid_api_key | 检查 Authorization: Bearer 或 X-API-Key；不要把完整 key 写进错误日志。 |
| 403 | membership_required / insufficient_scope | 检查当前套餐和 key 的 scope；scope 不能提升会员额度。 |
| 409 | idempotency_conflict / idempotency_in_progress | 同一业务请求保持同一个 key；冲突先停止，处理中等待后用同 key 重试。 |
| 413 | payload_too_large | 缩小请求体到当前套餐的 payload 限制以内，再重新发送。 |
| 429 | quota_exceeded / rate_limited / concurrency_limited | 读取 X-Quota-*、X-RateLimit-* 和 Retry-After；额度为 0 时停止，限速或并发时等待。 |
错误响应结构
{"object":"tool_api.error","error":{"code":"invalid_request","message":"Request body must be a JSON object."}}接口
GTIN API
按数量批量生成带有效校验位的 GTIN-14 值，用于开发和 Feed 质检。生成结果不是 GS1 正式分配的商品标识，额度按生成数量计算。
QR Code API
把链接或文本生成 SVG / PNG data URL 二维码。额度按请求次数计算。
UTM Builder API
把一条或多条落地页链接批量加上统一 UTM 参数；可选 id 和 sourcePlatform 会输出为 utm_id 与 utm_source_platform。额度按成功生成的链接数量计算。
Break-even ROAS API
输入售价、成本、物流、手续费和退款预留，返回盈亏平衡 ROAS、目标利润 ROAS 和 CPA 护栏。
OpenAPI JSON
/openapi.json