Farmatch API Docs

Formato padrão de erro

{
  "requestId": "f97e90f4-1cd6-44b6-9f6e-e2f09c94c6bf",
  "error": {
    "code": "invalid_api_key",
    "message": "API key inválida."
  }
}

Autenticação e autorização

Códigos de autenticação/tenant

Erros aplicáveis a todos os endpoints da API pública.

Nome	Tipo	Obrigatório	Descrição
`missing_api_key`	401	Não	Header x-api-key obrigatório não foi enviado.
`invalid_api_key`	401	Não	API key não encontrada.
`revoked_api_key`	403	Não	API key revogada.
`store_not_active`	403	Não	Loja vinculada à API key está inativa.

Erros de estoque

GET /api/v1/stock

Códigos estáveis para parâmetros de consulta.

Nome	Tipo	Obrigatório	Descrição
`invalid_limit`	400	Não	Parâmetro limit deve ser inteiro entre 1 e 200.
`invalid_cursor`	400	Não	Parâmetro cursor deve ser inteiro maior ou igual a 0.
`invalid_in_stock`	400	Não	Parâmetro inStock deve ser true ou false.
`invalid_updated_since`	400	Não	updatedSince deve ser timestamp (ms) ou data ISO válida.
`invalid_query`	400	Não	Parâmetro q acima do limite de 120 caracteres.

Erros de pedidos

POST /api/v1/orders

Códigos estáveis de validação de regras e negócio.

Nome	Tipo	Obrigatório	Descrição
`invalid_idempotency_key`	400	Não	x-idempotency-key acima de 120 caracteres.
`idempotency_key_mismatch`	400	Não	externalOrderId e x-idempotency-key com valores diferentes.
`payment_method_not_available`	400	Não	Forma de pagamento não disponível na loja.
`invalid_ean13`	400	Não	EAN13 vazio ou inválido em item do pedido.
`product_not_found`	400	Não	Produto não encontrado no catálogo global.
`product_not_available_in_store`	400	Não	Produto não disponível na loja autenticada.
`insufficient_stock`	409	Não	Estoque insuficiente para o item solicitado.
`order_creation_failed`	400	Não	Falha genérica na criação do pedido.

GET /api/v1/orders

Códigos estáveis para filtros de listagem.

Nome	Tipo	Obrigatório	Descrição
`invalid_limit`	400	Não	limit fora do intervalo permitido (1..200).
`invalid_status`	400	Não	status fora da lista de status válidos.

GET/PATCH /api/v1/orders/:orderId

Códigos estáveis para acesso ao pedido do tenant.

Nome	Tipo	Obrigatório	Descrição
`order_not_found_in_tenant`	404	Não	Pedido inexistente ou não pertencente à loja da API key.

Validação de schema (Zod)

Erros 400 sem code estável

Endpoints com zValidator retornam 400 quando o payload não corresponde ao schema esperado.

Nesses casos, o backend retorna uma estrutura de validação do Zod com detalhes de campos inválidos. Esse retorno pode variar conforme versão de dependências, portanto não há garantia de error.code estável para esse tipo de falha.

Erros