跳至内容
ShopentlyLearn
简体中文

错误代码

如果请求失败，请查看响应中的错误代码。在下方列表中展开对应代码，了解发生了什么以及如何处理。每个错误还附有响应示例和重试建议。

400request.malformed无法解析请求。
处理方法
检查 JSON 语法、URL 编码及请求结构。
重试策略
修正请求后重试。
响应 
{
  "error": {
    "code": "request.malformed",
    "fields": null,
    "message": "The request could not be read."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.invalid_credentialsAPI 密钥或访问令牌无效、过期或已撤销。
处理方法
检查商店 URL 和凭据。使用有效 API 密钥获取新令牌。
重试策略
修正身份验证后重试；避免反复发送无效令牌请求。
响应 
{
  "error": {
    "code": "authentication.invalid_credentials",
    "fields": null,
    "message": "The credentials are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.required缺少所需的 Authorization 请求头，或其方案不正确。
处理方法
签发或撤销令牌时，请在 Authorization 标头中使用 ApiKey 和 API 密钥。其他请求请使用 Bearer 和访问令牌。
重试策略
提供正确请求头后重试。
响应 
{
  "error": {
    "code": "authentication.required",
    "fields": null,
    "message": "Authentication is required."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.client_ip_unverified服务无法确定可信的客户端 IP 地址。
处理方法
请检查集成通过哪个 IP 地址连接 API。如果错误持续出现，请联系 Shopently 技术支持。
重试策略
解决 IP 地址识别问题后再试。
响应 
{
  "error": {
    "code": "authorization.client_ip_unverified",
    "fields": null,
    "message": "The client IP address could not be verified."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.ip_not_allowed源 IP 地址不在密钥允许的地址列表中。
处理方法
使用获准的源地址，或请获授权的管理员编辑密钥 IP 列表。
重试策略
只有在地址获准后才重试。
响应 
{
  "error": {
    "code": "authorization.ip_not_allowed",
    "fields": null,
    "message": "Access from this IP address is not allowed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.scope_denied密钥不具备此操作所需的有效权限。
处理方法
检查操作所需的权限及条件权限、密钥授权和签发者的访问权限。
重试策略
获授权的管理员授予所需权限后再重试。
响应 
{
  "error": {
    "code": "authorization.scope_denied",
    "fields": null,
    "message": "The required permission has not been granted."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.api_disabled此商店的 API 访问已禁用。
处理方法
请店主检查当前套餐及 API 可用性。
重试策略
启用 API 访问前不要重试。
响应 
{
  "error": {
    "code": "entitlements.api_disabled",
    "fields": null,
    "message": "API access is disabled for this store."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.limit_exceeded变更会超出当前套餐的限制。
处理方法
检查适用资源限制，并调整计划的变更或套餐。
重试策略
解决限制后重试；若请求改变，请使用新的幂等键。
响应 
{
  "error": {
    "code": "entitlements.limit_exceeded",
    "fields": null,
    "message": "The operation exceeds a plan limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.operation_disabled当前套餐不包含此操作。
处理方法
检查该操作注明的最低套餐。
重试策略
套餐允许操作且密钥具有所需权限后再重试。
响应 
{
  "error": {
    "code": "entitlements.operation_disabled",
    "fields": null,
    "message": "The current plan does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.resource_blocked套餐限制阻止访问此资源。
处理方法
请店主解决该资源的套餐限制。
重试策略
资源仍被阻止时，不要重复相同请求。
响应 
{
  "error": {
    "code": "entitlements.resource_blocked",
    "fields": null,
    "message": "A plan limit blocks access to this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

404resource.not_found资源不存在、已删除，或无法通过给定标识符访问。
处理方法
检查商店、资源路径和标识符。使用此商店返回的标识符。
重试策略
修正目标或确认目标存在后才重试。
响应 
{
  "error": {
    "code": "resource.not_found",
    "fields": null,
    "message": "The resource was not found."
  },
  "meta": {
    "request_id": "example-request"
  }
}

405request.method_not_allowed端点不支持此 HTTP 方法。
处理方法
使用文档规定的方法；Allow 响应头列出支持的方法。
重试策略
不要重试不支持的方法。
响应 
{
  "error": {
    "code": "request.method_not_allowed",
    "fields": null,
    "message": "This method is not supported for this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409idempotency.key_reused此幂等键属于另一个请求。
处理方法
查找原始操作。只有确实要进行新的逻辑操作时，才使用新密钥。
重试策略
不要使用冲突的密钥重试已改变的请求内容。
响应 
{
  "error": {
    "code": "idempotency.key_reused",
    "fields": null,
    "message": "This idempotency key was used with a different request."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.already_exists唯一值与现有资源冲突。
处理方法
读取现有资源，决定使用它还是选择其他唯一值。
重试策略
不要重复相同的冲突创建操作。
响应 
{
  "error": {
    "code": "resource.already_exists",
    "fields": null,
    "message": "A resource with these unique values already exists."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.in_use其他资源仍依赖此资源。
处理方法
检查依赖关系；删除前，通过支持的操作移除或修改依赖。
重试策略
处理依赖关系后重试。
响应 
{
  "error": {
    "code": "resource.in_use",
    "fields": null,
    "message": "The resource is still in use."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.state_conflict当前业务状态阻止此变更。
处理方法
读取当前状态并选择有效的业务状态转换。
重试策略
不要自动强制执行或反复提交冲突变更。
响应 
{
  "error": {
    "code": "resource.state_conflict",
    "fields": null,
    "message": "The current resource state does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.version_conflict在你读取版本后，另一次写入改变了资源。
处理方法
读取最新状态，协调变更，再提交新的 expected_version。
重试策略
为调整后的操作使用新的幂等键；不要盲目覆盖。
响应 
{
  "error": {
    "code": "resource.version_conflict",
    "fields": null,
    "message": "The resource version has changed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409storage.limit_reached图片和文件存储空间已达上限。请释放空间或提高限额。
处理方法
图片和文件存储空间已达上限。请释放空间或提高限额。
重试策略
使用各自的幂等键重试更小且有效的操作。
响应 
{
  "error": {
    "code": "storage.limit_reached",
    "fields": null,
    "message": "The upload storage limit is reached."
  },
  "meta": {
    "request_id": "example-request"
  }
}

413request.too_large请求超出大小限制。
处理方法
减小请求内容，或将工作拆分为支持的独立操作。
重试策略
使用各自的幂等键重试更小且有效的操作。
响应 
{
  "error": {
    "code": "request.too_large",
    "fields": null,
    "message": "The request exceeds the size limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

415request.unsupported_media_type不支持该媒体类型或内容编码。
处理方法
JSON 写入使用 Content-Type: application/json，并发送受支持的未压缩请求体。
重试策略
修正媒体类型或编码后重试。
响应 
{
  "error": {
    "code": "request.unsupported_media_type",
    "fields": null,
    "message": "The request media type or encoding is not supported."
  },
  "meta": {
    "request_id": "example-request"
  }
}

416request.range_not_satisfiable约束: Range
处理方法
Range: bytes=0-(size_bytes-1)
重试策略
修正请求后重试。
响应 
{
  "error": {
    "code": "request.range_not_satisfiable",
    "fields": null,
    "message": "The requested byte range is unavailable."
  },
  "meta": {
    "request_id": "example-request"
  }
}

422request.validation_failed一个或多个字段或参数未通过验证。
处理方法
查看 error.fields，再检查必填字段、是否允许 null、标识符和允许值。
重试策略
修正请求后重试；已改变的写入属于新的逻辑操作。
响应 
{
  "error": {
    "code": "request.validation_failed",
    "fields": null,
    "message": "Some request parameters are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.queue_fullAPI 短队列已满；请求尚未开始执行。
处理方法
将请求排入队列，并遵守 Retry-After 响应头。
重试策略
请至少等待 Retry-After 指定的秒数。如果重试写入，请保持相同的请求正文和 Idempotency-Key 值。
响应 
{
  "error": {
    "code": "capacity.queue_full",
    "fields": null,
    "message": "The API is busy. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.wait_timeoutAPI 队列等待超时；请求尚未开始执行。
处理方法
将请求排入队列，并遵守 Retry-After 响应头。
重试策略
请至少等待 Retry-After 指定的秒数。如果重试写入，请保持相同的请求正文和 Idempotency-Key 值。
响应 
{
  "error": {
    "code": "capacity.wait_timeout",
    "fields": null,
    "message": "The API could not start this request in time. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429rate_limit.exceeded请求速率超出适用限制。
处理方法
将请求排入队列，并遵守 Retry-After 响应头。
重试策略
请至少等待 Retry-After 指定的秒数。如果重试写入，请保持相同的请求正文和 Idempotency-Key 值。
响应 
{
  "error": {
    "code": "rate_limit.exceeded",
    "fields": null,
    "message": "The request rate limit has been exceeded."
  },
  "meta": {
    "request_id": "example-request"
  }
}

500internal.error发生意外服务错误。
处理方法
稍等片刻再重新发送请求。如果错误 500 再次出现，请联系 Shopently 技术支持，并提供请求 ID。
重试策略
稍等片刻后，可以重新尝试读取数据。重试写入时，请使用相同的 Idempotency-Key 值，并保持请求正文不变。
响应 
{
  "error": {
    "code": "internal.error",
    "fields": null,
    "message": "An unexpected error occurred."
  },
  "meta": {
    "request_id": "example-request"
  }
}

502gateway.bad_response网关未收到有效的 API 响应。
处理方法
保留请求标识符。失败响应不代表写入未被执行。
重试策略
使用次数受限的退避重试；重复同一逻辑写入时，保留原始 Idempotency-Key 和请求内容。
响应 
{
  "error": {
    "code": "gateway.bad_response",
    "fields": null,
    "message": "The API gateway could not obtain a valid response."
  },
  "meta": {
    "request_id": "example-request"
  }
}

503service.unavailableAPI 暂时无法处理请求。
处理方法
如果响应包含 Retry-After 标头，请等待指定秒数后再试。如果没有，请稍等片刻。若错误持续出现，请联系 Shopently 技术支持，并提供请求 ID。
重试策略
按上述说明等待后再试。重试写入时，请使用相同的 Idempotency-Key 值，并保持请求正文不变。
响应 
{
  "error": {
    "code": "service.unavailable",
    "fields": null,
    "message": "The API is temporarily unavailable."
  },
  "meta": {
    "request_id": "example-request"
  }
}

504gateway.timeout网关等待 API 响应超时。
处理方法
如果请求修改了数据，请检查更改是否已保存在商店中。未收到响应并不代表写入失败。如果错误持续出现，请联系 Shopently 技术支持，并提供请求 ID。
重试策略
稍等片刻后，可以重新尝试读取数据。重试写入时，请使用相同的 Idempotency-Key 值，并保持请求正文不变。
响应 
{
  "error": {
    "code": "gateway.timeout",
    "fields": null,
    "message": "The API gateway timed out."
  },
  "meta": {
    "request_id": "example-request"
  }
}