Erros e Respostas

A API segue os códigos HTTP padrão e retorna respostas JSON consistentes.

Formato da resposta

Sucesso — item único

{
  "data": {
    "id": 1,
    "name": "Produto Exemplo"
  }
}

Sucesso — listagem paginada

{
  "data": [
    { "id": 1, "name": "Produto A" },
    { "id": 2, "name": "Produto B" }
  ],
  "links": {
    "first": "https://sualoja.com.br/api/v1/products?page=1",
    "last": "https://sualoja.com.br/api/v1/products?page=5",
    "prev": null,
    "next": "https://sualoja.com.br/api/v1/products?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "per_page": 25,
    "to": 25,
    "total": 120
  }
}

Sucesso — exclusão

{
  "message": "Produto removido."
}

Códigos de status

Código	Significado	Quando ocorre
200	OK	Requisição processada com sucesso
201	Created	Recurso criado com sucesso (POST)
401	Unauthorized	API key ausente, inválida ou expirada
404	Not Found	Recurso não encontrado
422	Unprocessable Entity	Erro de validação ou restrição de integridade
429	Too Many Requests	Rate limit excedido (60 req/min)
500	Server Error	Erro interno do servidor

Erros de validação

Quando os dados enviados não passam na validação, a API retorna 422 com os campos e mensagens de erro:

HTTP/1.1 422 Unprocessable Entity

{
  "message": "Dados inválidos.",
  "errors": {
    "name": [
      "O campo nome é obrigatório."
    ],
    "price": [
      "O campo preço deve ser um número.",
      "O campo preço deve ser pelo menos 0."
    ]
  }
}

Erros de integridade

Ao tentar excluir um recurso que possui vínculos:

HTTP/1.1 422 Unprocessable Entity

{
  "message": "Não é possível excluir: 15 produto(s) vinculado(s)."
}

Paginação

Todas as listagens suportam paginação via query params:

Parâmetro	Padrão	Máximo	Descrição
page	1	—	Página atual
per_page	25	100	Itens por página

Exemplo:

GET /api/v1/products?page=2&per_page=50

Ordenação

A maioria das listagens suporta ordenação:

Parâmetro	Padrão	Descrição
sort	varia por recurso	Campo para ordenação
direction	desc	asc ou desc

Exemplo:

GET /api/v1/products?sort=price&direction=asc

Content-Type

Todas as requisições que enviam dados (POST, PUT) devem incluir:

Content-Type: application/json
Accept: application/json