Erros & Códigos

Esta é a fonte única de verdade sobre erros da API. Todos os endpoints seguem o mesmo envelope e o mesmo conjunto de códigos de status descritos aqui. As páginas de recurso não repetem esta informação — elas apenas referenciam esta página.

Envelope de erro

Toda resposta de falha usa o mesmo formato:

{
  "message": "string",
  "errors": {
    "campo": ["mensagem"]
  }
}

• message: descrição legível do erro. Sempre presente.
• errors: mapa de campo para lista de mensagens. Aparece apenas em falhas de validação (422) e somente quando há erros associados a campos específicos.

Nota

Respostas de sucesso usam um envelope diferente, com message e data. Veja o formato em Autenticação e nas páginas de cada recurso.

Códigos de status HTTP

Status	Significado	Quando ocorre
400 Bad Request	Requisição malformada	Corpo ilegível, parâmetro com formato inválido ou pré-condição da requisição não atendida.
401 Unauthorized	Não autenticado	Token ausente, inválido ou expirado no header Authorization.
403 Forbidden	Sem permissão	Token válido, mas o usuário não tem papel/permissão para a operação.
404 Not Found	Não encontrado	Recurso inexistente ou fora do contexto da empresa resolvida pelo token.
409 Conflict	Conflito de estado	Violação de unicidade (e-mail/documento duplicado) ou operação que conflita com o estado atual (ex.: remover pipeline com negócios).
422 Unprocessable	Falha de validação	Corpo sintaticamente válido, mas com campos que não passam nas regras. Inclui errors.
429 Too Many Requests	Limite excedido	Excesso de requisições. Detalhes em Rate limiting.
500 Server Error	Erro interno	Falha inesperada no servidor. A requisição pode ser repetida.

Cuidado

A causa de um 404 pode ser um recurso que existe em outra empresa. Como a empresa é resolvida automaticamente a partir do token, recursos de outras empresas são tratados como inexistentes — nunca como 403.

Exemplos por status

400 — Bad Request

{
  "message": "Requisição malformada."
}

401 — Unauthorized

{
  "message": "Não autenticado."
}

403 — Forbidden

{
  "message": "Você não tem permissão para executar esta ação."
}

404 — Not Found

{
  "message": "Registro não encontrado."
}

409 — Conflict

{
  "message": "Já existe um registro com este valor."
}

422 — Unprocessable Entity

{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "email": ["O campo e-mail é obrigatório."],
    "value": ["O campo valor deve ser um número inteiro."]
  }
}

429 — Too Many Requests

{
  "message": "Muitas requisições. Tente novamente mais tarde."
}

Os headers de controle (X-RateLimit-*, Retry-After) e os limites por rota são descritos em Rate limiting.

500 — Internal Server Error

{
  "message": "Erro interno do servidor."
}

Endpoint de teste

Para inspecionar o formato exato das respostas de erro em integração, a API expõe um endpoint de diagnóstico que devolve o envelope de erro correspondente ao status solicitado.

GET /errors/sample Copiar para LLM

Amostra de erro

Retorna o envelope de erro padronizado para o status informado. Útil para validar o tratamento de falhas na integração.

Parâmetros de query

Campo	Tipo	Obrigatório	Descrição
status	integer	Sim	Código HTTP a simular (400, 401, 403, 404, 409, 422, 429 ou 500).

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X GET https://api.maestron.com.br/v1/errors/sample \
  -H "Authorization: Bearer SEU_TOKEN"

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.maestron.com.br/v1/errors/sample', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
response = requests.get(
    "https://api.maestron.com.br/v1/errors/sample",
    headers=headers,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/v1/errors/sample", {
  method: "GET",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
  },
});
const data = await response.json();

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "SEU_TOKEN");
var response = await client.GetAsync("https://api.maestron.com.br/v1/errors/sample");
var data = await response.Content.ReadAsStringAsync();

GET /errors/sample HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN

Respostas

400 · Bad Request401 · Unauthorized403 · Forbidden404 · Not Found409 · Conflict422 · Unprocessable Entity429 · Too Many Requests500 · Internal Server Error

{
  "message": "Requisição malformada."
}

{
  "message": "Não autenticado."
}

{
  "message": "Você não tem permissão para executar esta ação."
}

{
  "message": "Registro não encontrado."
}

{
  "message": "Já existe um registro com este valor."
}

{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "status": [
      "O campo status é obrigatório."
    ]
  }
}

{
  "message": "Muitas requisições. Tente novamente mais tarde."
}

{
  "message": "Erro interno do servidor."
}

Boas práticas de tratamento

• Trate o status HTTP como fonte primária de decisão; use message para exibição e errors para mapear falhas por campo.
• O campo errors só está presente em 422. Não dependa dele em outros status.
• Para 429, consulte os headers de controle descritos em Rate limiting.
• Para 401, renove o token de acordo com o fluxo descrito em Autenticação.