Erros¶

A API utiliza o formato Problem Details (RFC 7807) para todos os erros.

Formato padrão de erro¶

{
  "status": 404,
  "title": "CHECKIN_NOT_FOUND",
  "detail": "Check-in não encontrado.",
  "instance": "/api/v1/checkins/3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "correlationId": "2b3c4d5e-aaaa-bbbb-cccc-000000000002"
}

Campo	Descrição
`status`	Código HTTP
`title`	Código de erro legível por máquina
`detail`	Mensagem legível para humanos
`instance`	Path da requisição que gerou o erro
`correlationId`	ID para rastrear o erro junto ao suporte

Tabela de erros por HTTP status¶

401 — Unauthorized¶

Título	Situação
`Unauthorized`	Token JWT ausente, inválido ou expirado. Obtenha um novo token via `POST /auth/token`.
`Unauthorized`	ClientId ou ClientSecret inválidos ao tentar autenticar.

404 — Not Found¶

Título	Situação	Ação
`TENANT_NOT_FOUND`	Tenant não encontrado.	Verifique se o token está correto e pertence a um tenant ativo.
`CHECKIN_NOT_FOUND`	Check-in não encontrado com o ID informado.	Verifique se o ID existe e pertence ao seu tenant.

409 — Conflict¶

Não utilizado nesta versão. Check-ins duplicados retornam 200 OK com isDuplicate: true.

422 — Unprocessable Entity¶

Erros de validação de campos obrigatórios ou formato inválido.

{
  "status": 422,
  "errors": {
    "source": ["O campo 'source' é obrigatório."],
    "partnerTransactionId": ["O campo 'partnerTransactionId' é obrigatório."]
  }
}

Situação	Ação
Campos obrigatórios ausentes	Inclua todos os campos obrigatórios
`status` inválido no Student Sync	Use apenas `ACTIVE` ou `INACTIVE`
`source` inválido no Check-in	Use `INTERNAL` nesta etapa
`TENANT_NOT_OPERATIONAL`	O tenant está temporariamente inativo. Contate o suporte.

500 — Internal Server Error¶

Erro inesperado na plataforma. Registre o correlationId da resposta e entre em contato com o suporte.

{
  "status": 500,
  "title": "INTERNAL_ERROR",
  "detail": "Erro interno. Contate o suporte com o correlationId.",
  "correlationId": "2b3c4d5e-aaaa-bbbb-cccc-000000000002"
}

Ação: nunca tente re-enviar automaticamente após um 500 sem verificar o estado do recurso, pois a operação pode ter sido parcialmente executada.

Erros de validação de check-in (não são códigos HTTP)¶

Estes valores aparecem no campo rejectionReason ao consultar GET /api/v1/checkins/{id}:

Código	Significado	Ação
`STUDENT_NOT_FOUND`	Aluno não encontrado pelo `externalStudentId` informado	Sincronize o aluno via `POST /students/sync`
`STUDENT_INACTIVE`	Aluno está com `status: INACTIVE` na plataforma	Re-ative o aluno via `POST /students/sync` com `status: ACTIVE`
`STUDENT_SUSPENDED`	Aluno temporariamente suspenso	Aguarde a reativação ou contate o suporte
`AUTHORIZATION_EXPIRED`	Autorização do aluno venceu	Verifique a situação do aluno no sistema principal

Boas práticas para tratamento de erros¶

401: renove o token imediatamente antes de re-tentar a requisição original
422: corrija o payload — re-tentar sem correção resultará no mesmo erro
404 em check-in: verifique o ID — pode ser de outro tenant ou não existir
500: registre o correlationId e aguarde alguns segundos antes de re-tentar
Timeouts de rede: re-tente com o mesmo partnerTransactionId — a idempotência garante que não haverá duplicação

Header de rastreabilidade¶

Você pode enviar um X-Correlation-Id customizado em todas as requisições para facilitar a rastreabilidade no seu sistema:

X-Correlation-Id: meu-sistema-txn-abc123

Se não enviado, a plataforma gera um automaticamente e retorna no campo correlationId da resposta de erro.