在使用 Makers 开发项目时，您可能会遇到各种错误。当访问您的站点出现问题时，页面将显示错误码及简要说明。这些错误可能涉及项目级别的访问问题或部署级别的状态异常。本章将针对常见错误情况提供具体解决方案。
错误码列表
状态码 | 错误码 | 说明 |
400 | - | Agent 请求头 makers-conversation-id 无效或缺失。 |
401 | UNAUTHORIZED | 预览链接鉴权信息失效。 |
404 | NOT_FOUND | 该站点不存在。 |
410 | DELETED | 该部署已经删除。 |
413 | CLOUD_FUNCTION_PAYLOAD_TOO_LARGE | Cloud Functions 请求大小超出限制。 |
423 | DEPLOYING | 项目正在部署中。 |
424 | FAILED | 项目部署失败。 |
429 | - | Agent 并发会话数超出限制。 |
429 | RATE_LIMIT_EXCEEDED | 请求频率超出限制。 |
451 | UNAVAILABLE | 项目已被封禁。 |
500 | CLOUD_FUNCTION_RESPONSE_PAYLOAD_TOO_LARGE | Cloud Functions 响应大小超出限制。 |
| INTERNAL_CLOUD_FUNCTION_ERROR | Cloud Functions 内部错误。 |
| INTERNAL_CLOUD_FUNCTION_INVOCATION_FAILED | Cloud Functions 内部调用失败。 |
| INTERNAL_CLOUD_FUNCTION_NOT_READY | Cloud Functions 初始化失败。 |
502 | CLOUD_FUNCTION_INVOCATION_FAILED | Cloud Functions 调用失败。 |
503 | CLOUD_FUNCTION_SERVICE_UNAVAILABLE | Cloud Functions 服务不可用。 |
504 | CLOUD_FUNCTION_INVOCATION_TIMEOUT | Cloud Functions 调用超时。 |
511 | EDGE_FUNCTION_INVOCATION_LIMIT_EXCEEDED | Edge Functions 调用超限。 |
512 | CLOUD_FUNCTION_INVOCATION_LIMIT_EXCEEDED | Cloud Functions 调用超限。 |
错误码详情
400 - 请求头无效
发往 Agent（
agent-node / agent-python）路由的请求必须携带合法的 makers-conversation-id 请求头，否则返回 400。该请求头要求：必填、长度 6–36 个字符、仅允许 0-9 a-z A-Z - _ .。请检查并修正请求头后重试。401 - 鉴权信息失效 UNAUTHORIZED
为保障内容合规，通过 项目域名 及 部署域名 访问 Makers 站点需遵循以下规则：
1. 项目加速区域设置为“中国大陆可用区”或“全球可用区（含中国大陆）”：
1.1 须使用系统生成的预览链接进行访问，该链接有效期为 3 小时，超时后将返回 401 错误。
1.2 可通过控制台“项目概览”界面右上角的“预览”按钮定期更新有效链接。
2. 项目加速区域设置为“全球可用区（不含中国大陆）”：
2.1 非中国大陆网络环境可直接访问，中国大陆网络环境将返回 401 错误。
404 - 站点不存在 NOT_FOUND
请确认您访问的项目域名或部署域名是否正确。
410 - 部署已删除 DELETED
当您删除某条部署记录后，再尝试访问该部署域名时，将返回 410 错误。部署可能因为版本更新、资源优化或管理需求而被删除。已删除的部署无法恢复，您可以选择创建新的部署。
413 - 请求大小超限 CLOUD_FUNCTION_PAYLOAD_TOO_LARGE
Cloud Functions 请求事件大小超出限制，可尝试精简函数的入参，若涉及文件传入，建议将文件上传至腾讯云 COS。
423 - 项目正在部署中 DEPLOYING
如果项目正在进行首次部署，请耐心等待部署完成后再次访问。如果是非首次部署，您仍然可以访问项目，但将看到旧版本，待新部署完成后即可访问最新版本。
424 - 部署失败 FAILED
项目在构建过程中出现错误或其他原因导致部署失败将会出现 424 错误。
常见的失败原因包括：
构建脚本错误。
依赖项缺失或版本不兼容。
资源限制（如内存不足）。
请在控制台查看对应项目的部署记录详情以获取日志，了解具体的失败原因。修复问题后，您可以重新创建部署。
429 - 请求过多
并发会话超限（仅 Agent 路由）：当项目的并发会话数达到上限时，新的 Agent 请求会被拒绝并返回 429（响应头
Retry-After: 10），错误信息为 “Too many concurrent requests for this zone”。会话由 makers-conversation-id 唯一标识，在有效期内复用同一 ID 不会占用新的并发位。具体并发上限见 限制与配额。请求频率超限
RATE_LIMIT_EXCEEDED：站点所有请求受全站频率限制，超限时返回 429（响应头 Retry-After: 60），提示 “Too many requests. Please try again later.”。遇到 429 时，请按响应头
Retry-After 指定的时间退避后重试。451 - 项目已被封禁 UNAVAILABLE
由于违反平台规则，如涉及非法内容（涉黄、涉政等），项目被封禁且无法访问。请确保您的内容符合法律法规和平台规定。如果您认为这是一个误判，请通过社群或客服与我们联系以获取更多信息。
500
响应大小超限 CLOUD_FUNCTION_RESPONSE_PAYLOAD_TOO_LARGE
Cloud Functions 响应大小超出限制，请调整函数返回值大小后重试。
内部错误 INTERNAL_CLOUD_FUNCTION_ERROR
函数内部调用失败 INTERNAL_CLOUD_FUNCTION_INVOCATION_FAILED
函数未就绪 INTERNAL_CLOUD_FUNCTION_NOT_READY
502 - 函数调用失败 CLOUD_FUNCTION_INVOCATION_FAILED
Cloud Functions 调用失败，通常在您的代码执行错误时返回，请根据错误信息检查代码。更多信息请查看控制台函数日志。
503 - 函数服务不可用 CLOUD_FUNCTION_SERVICE_UNAVAILABLE
Cloud Functions 服务不可用，请检查业务代码逻辑是否存在内存泄漏。
504 - 函数调用超时 CLOUD_FUNCTION_INVOCATION_TIMEOUT
Cloud Functions 调用超时，请检查业务代码执行时长是否超过平台限制。
511 - 边缘函数调用超限 EDGE_FUNCTION_INVOCATION_LIMIT_EXCEEDED
512 - 函数调用超限 CLOUD_FUNCTION_INVOCATION_LIMIT_EXCEEDED
常见问题
Q: 我遇到了上述未提及的错误码，该怎么办？
A：如果您遇到了文档中未涵盖的错误码，请记录下错误码和您的操作步骤，然后联系我们寻求帮助。
Q: 如何防止预览链接失效导致的 401 错误？
A：最好的方法是为您的项目添加一个自定义域名。这样可以确保您始终可以通过该域名访问您的项目，而不依赖于有时效性的预览链接。
Q: 我的项目一直显示 423 错误（正在部署中），但似乎已经很久了，这正常吗？
A：通常情况下，部署过程应该在几分钟内完成。如果您发现部署时间异常地长，建议检查您的部署日志，看是否有任何错误信息。如果问题持续，请联系我们。
