Solução de Problemas

Referência rápida para os erros e situações mais comuns durante uma integração com a API Obra Play.

---

Erros de autenticação

401 Unauthorized

O servidor não conseguiu autenticar a requisição.

Causas comuns:

• Header Authorization ausente ou com formato incorreto
• Token inválido ou revogado

Como resolver:

Verifique se o header está exatamente nesse formato (note o espaço após Token):

Authorization: Token 36434d218c36630f668af3dc089aea78ff63b98c

Se estiver usando JWT, confirme que o token access não expirou. Se expirou, renove via /auth/jwt/refresh/.

---

403 Forbidden

A autenticação funcionou, mas o usuário não tem permissão para acessar aquele recurso.

Causas comuns:

• Tentando acessar um recurso de outra empresa
• Usuário sem o perfil adequado (ex: usuário sem is_supplier tentando criar respostas de cotação)
• Ação não permitida no estado atual do recurso (ex: finalizar uma cotação já cancelada)

Como resolver:

Verifique os dados do usuário autenticado:

GET /auth/users/me/

Confirme que o campo is_supplier é true para operações de fornecedor.

---

Erros de validação

400 Bad Request

Os dados enviados não passaram pela validação da API.

A resposta inclui detalhes específicos sobre cada campo com problema:

{
  "company": [
    "Pk inválido \"9999\" - objeto não existe."
  ],
  "quotation": {
    "shipping_addresses": [
      "Este campo é obrigatório."
    ]
  }
}

Para erros de regra de negócio (não vinculados a um campo específico):

{
  "detail": "Quotation already canceled"
}

Como resolver:

Leia o corpo da resposta de erro — ele sempre descreve exatamente qual campo ou regra falhou. Corrija os dados e reenvie.

---

Rate limiting

429 Too Many Requests

Sua integração excedeu o limite de requisições permitidas em um intervalo de tempo.

A resposta inclui o header Retry-After indicando quantos segundos aguardar:

HTTP/1.1 429 Too Many Requests
Retry-After: 30

Como resolver:

• Implemente um mecanismo de retry com backoff exponencial
• Evite fazer polling em loops rápidos — prefira Webhooks para receber eventos
• Agrupe requisições sempre que possível

---

Erros do servidor

500 Internal Server Error

Erro inesperado no servidor da Obra Play.

Como resolver:

• Aguarde alguns segundos e tente novamente
• Se o erro persistir, entre em contato com o suporte informando:
  • Rota da requisição
  • Payload enviado
  • Timestamp do erro

---

Problemas comuns

Respostas em inglês

Por padrão a API retorna mensagens de erro em inglês. Para receber em português, adicione o header:

Accept-Language: pt-br

---

Envio de arquivos retorna erro

Para uploads, o Content-Type deve ser multipart/form-data, não application/json:

POST /api/orders/5521/supplier_uploads/
Authorization: Token seu_token_aqui
Content-Type: multipart/form-data

file=@nota_fiscal.pdf

Verifique também:

• Tamanho máximo: 30 MB por arquivo
• Formatos aceitos: PDF, JPG, PNG, XLSX, XLS, CSV

---

Paginação — dados incompletos

Se uma listagem parece retornar dados incompletos, verifique se está iterando todas as páginas. A resposta sempre indica o total de registros e a URL da próxima página:

{
  "count": 350,
  "next": "https://api.obraplay.com/api/quotations/?page=2",
  "previous": null,
  "results": [ ... ]
}

Continue fazendo requisições enquanto next não for null.

---

Webhook não está sendo recebido

1. Confirme que a URL cadastrada está acessível publicamente (não pode ser localhost)
2. Verifique se seu endpoint retorna status 2xx em até 5 segundos
3. Certifique-se de que seu servidor aceita requisições POST com Content-Type: application/json
4. Durante desenvolvimento, use ngrok para expor seu ambiente local

---

Referência de códigos HTTP

Código	Significado	Ação recomendada
200 OK	Sucesso	—
201 Created	Recurso criado com sucesso	—
400 Bad Request	Dados inválidos	Leia o corpo da resposta e corrija os dados
401 Unauthorized	Não autenticado	Verifique o token no header Authorization
403 Forbidden	Sem permissão	Verifique o perfil do usuário e o estado do recurso
404 Not Found	Recurso não encontrado	Confirme o ID/slug e se o usuário tem acesso a ele
429 Too Many Requests	Rate limit atingido	Aguarde o tempo indicado no header Retry-After
500 Internal Server Error	Erro no servidor	Aguarde e tente novamente; contate o suporte se persistir