Tratamento de Erros

REST API — Todos os endpoints requerem autenticação via Bearer token. Inclua Authorization: Bearer {token} em cada requisição. Os tokens são gerenciados em Configurações do GitScrum → API. Base URL: https://services.gitscrum.com — Todos os caminhos de requisição nesta documentação são relativos a esta URL base.

A API do GitScrum utiliza códigos de status HTTP padrão e retorna respostas de erro JSON estruturadas.

Códigos de status HTTP

Formato de resposta de erro

Todas as respostas de erro seguem uma estrutura consistente:

{
  "error": "Not Found",
  "message": "The requested resource was not found."
}

Erros de validação (422)

Erros de validação incluem detalhes por campo:

{
  "error": "Validation Error",
  "message": "The given data was invalid.",
  "errors": {
    "title": ["The title field is required."],
    "company_slug": ["The selected company slug is invalid."]
  }
}

Cada chave no objeto errors corresponde a um campo da requisição, e o valor é um array de mensagens de validação.

Erros de autenticação (401)

{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}

Verifique se seu token é válido e está incluído no header Authorization. Veja Autenticação.

Erros de permissão (403)

{
  "error": "Forbidden",
  "message": "You do not have permission to perform this action."
}

Verifique se sua conta possui a função necessária para o workspace ou projeto.

Boas práticas

• Verifique códigos de status — Sempre inspecione o código de status HTTP antes de processar o corpo da resposta.
• Trate retentativas — Retente erros 429 e 5xx com backoff exponencial. Não retente erros 4xx de cliente.
• Registre erros — Capture a resposta de erro completa (status, message, objeto errors) para depuração.
• Valide localmente — Valide campos obrigatórios antes de enviar requisições para evitar respostas 422 desnecessárias.
• Exiba mensagens — Use o campo message para exibir feedback de erro amigável ao usuário.