错误码 - BrazilScope Docs

错误码

HTTP	code	说明
400	`BAD_REQUEST`	请求参数缺失或格式错误
401	`UNAUTHORIZED`	缺少或无效的 API Key / Token
403	`FORBIDDEN`	无权限访问该资源（如需订阅）
404	`NOT_FOUND`	CNPJ 不存在或未收录
409	`CONFLICT`	资源冲突（如重复创建）
422	`UNPROCESSABLE`	参数语义校验未通过
429	`RATE_LIMITED`	超出速率/配额限制
500	`INTERNAL`	服务端内部错误
503	`SOURCE_UNAVAILABLE`	上游政府数据源暂不可用

错误响应示例

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "CNPJ 11222333000181 未收录",
    "request_id": "req_8f3a",
    "details": { "cnpj": "11222333000181" }
  }
}

排障建议

记录 request_id 与 HTTP 状态码。

401：确认 Authorization 格式为 Bearer <API_KEY>，且 Key 未被删除。

403：确认套餐包含该能力（如 detail=1、AI 报告）。

404：先校验 CNPJ 校验位；平台已离线导入全量数据，未命中即为未收录。

429：按 Retry-After 退避；高频批量场景请升级套餐或改用批量能力。

503：上游数据源暂不可用，稍后重试。