Errors - Qoder CN Series: Central de Documentação do Alibaba Cloud

Formato unificado de envelope de erros, tipos de erro e práticas de solução de problemas para a API do Qoder cloud Agents.

A API do Qoder cloud Agents retorna todos os erros em um formato de envelope unificado. Cada resposta de erro contém informações estruturadas para tratamento programático e solução de problemas.

Formato do envelope de erros

Todas as respostas de erro seguem esta estrutura JSON:

{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "<error_type>",
    "message": "<human-readable error description>",
    "param": "<name of the parameter that triggered the error (optional)>"
  }
}

Descrição dos campos

Campo	Tipo	Obrigatório	Descrição
`type`	string	Sim	Sempre `"error"`
`request_id`	string	Sim	ID de correlação da requisição proveniente de `x-request-id`; um UUID gerado pelo servidor caso não seja fornecido
`error.type`	string	Sim	Identificador do tipo de erro
`error.message`	string	Sim	Descrição legível do erro
`error.param`	string	Não	Nome do parâmetro da requisição que acionou o erro

Visão geral dos tipos de erro

Código de status HTTP	`error.type`	Descrição
400	`invalid_request_error`	Parâmetros de requisição inválidos ou ausentes
401	`authentication_error`	Falha na autenticação; token inválido ou ausente
403	`permission_error`	Autenticação bem-sucedida, mas acesso negado ao recurso de destino
404	`not_found_error`	O recurso de destino não existe
409	`conflict_error`	Conflito de estado do recurso (por exemplo, criação duplicada)
500	`api_error`	Erro interno do servidor

Detalhes dos tipos de erro

400 — invalid_request_error

O formato ou os parâmetros da requisição são inválidos.

Causas comuns:

Ausência de um campo obrigatório (por exemplo, name)
Tipo de valor incorreto no campo (por exemplo, esperava-se uma string, mas foi fornecido um number)
Corpo da requisição excede o limite de tamanho de 4 MB
JSON malformado

{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "invalid_request_error",
    "message": "Missing required field: name",
    "param": "name"
  }
}

# Trigger example: missing the name field
curl -X POST "https://api.qoder.com.cn/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{}'

401 — authentication_error

Falha na autenticação.

Causas comuns:

Nenhum cabeçalho Authorization fornecido
Formato de PAT malformado
PAT expirado ou revogado
Uso de x-api-key em vez de um Bearer Token

{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key or token."
  }
}

# Trigger example: using an invalid token
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents" \
  -H "Authorization: Bearer pt-invalid-token"

403 — permission_error

A autenticação foi bem-sucedida, mas você não tem as permissões necessárias.

Causas comuns:

O PAT não tem acesso ao Agent de destino (ele pertence a outro usuário ou organização)
O escopo de permissão do PAT não abrange a operação atual
Tentativa de operar em um recurso arquivado e bloqueado

{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "permission_error",
    "message": "You do not have permission to access this agent."
  }
}

# Trigger example: accessing another user's Agent
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents/agent_other_user_123" \
  -H "Authorization: Bearer $QODER_PAT"

404 — not_found_error

O recurso de destino não existe.

Causas comuns:

ID do Agent/Session/Environment inexistente
Recurso excluído
Erro de digitação no caminho da url

{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "not_found_error",
    "message": "Agent not found: agent_nonexistent_123"
  }
}

# Trigger example: querying a non-existent Agent
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents/agent_nonexistent_123" \
  -H "Authorization: Bearer $QODER_PAT"

409 — conflict_error

Conflito de estado do recurso; a operação não pode ser executada.

Causas comuns:

Requisição repetida usando a mesma chave de idempotência, mas com um corpo de requisição diferente
Tentativa de continuar operando em uma Session já encerrada
Criação duplicada de um recurso com nome exclusivo

{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "conflict_error",
    "message": "A request with this idempotency key has already been processed with different parameters."
  }
}

500 — api_error

Erro interno do servidor.

Causas comuns:

Service temporariamente indisponível
Exceção em componente interno
Timeout de conexão com o banco de dados

{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "api_error",
    "message": "An internal error occurred. Please try again later."
  }
}

Quando ocorrer um erro 500, utilize uma estratégia de nova tentativa com backoff exponencial (aguarde 1s, 2s, 4s).

Melhores práticas para tratamento de erros

**Analise error.type** para tratar erros programaticamente, em vez de depender apenas dos códigos de status HTTP
**Registre nos logs request_id e error.message** para facilitar a solução de problemas
**Se presente, verifique error.param** para localizar rapidamente o campo problemático
Não tente novamente erros 4xx (a menos que tenha modificado os parâmetros da requisição)
Use novas tentativas com backoff para erros 5xx (máximo de 3 tentativas)

# Example request with error handling
response=$(curl -s -w "\n%{http_code}" \
  "https://api.qoder.com.cn/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_PAT")

# Extract HTTP status code
http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | sed '$d')

if [ "$http_code" -ge 400 ]; then
  # Extract error type
  error_type=$(echo "$body" | python3 -c "import sys,json; print(json.load(sys.stdin)['error']['type'])")
  echo "API error: $error_type"
fi