Saltar para o conteúdo principal

​
Tratamento de Erros

A API utiliza códigos de estado HTTP padrão e devolve corpos de erro JSON consistentes para todos os casos de falha.

​
Códigos de estado HTTP

CódigoSignificadoCausa comum
200OKPedido bem-sucedido
201CreatedRecurso foi criado
204No ContentRecurso foi eliminado
400Bad RequestCorpo do pedido malformado
401UnauthorizedHeader Authorization ausente ou inválido
403ForbiddenToken válido, mas sem permissões suficientes
404Not FoundRecurso não existe ou pertence a outro tenant
422Unprocessable EntityValidação falhou (consulte o campo errors)
429Too Many RequestsLimite de taxa excedido
500Internal Server ErrorErro inesperado no servidor

​
Corpo da resposta de erro

Todas as respostas de erro devolvem um corpo JSON. A estrutura varia consoante o tipo de erro.

​
Erro de validação (422)

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required.", "The email must be a valid email address."],
    "course_uuid": ["The selected course uuid is invalid."]
  }
}
O objeto errors mapeia nomes de campos para um array de mensagens legíveis.

​
Erro de autenticação (401)

{
  "message": "Unauthenticated."
}

​
Não encontrado (404)

{
  "message": "No query results for model [App\\Certificate] 550e8400-e29b-41d4-a716-446655440000"
}

​
Erro genérico do servidor (500)

{
  "message": "Server Error"
}

​
Tratando erros no código

async function createCertificate(payload) {
  const response = await fetch('https://api.dokstamp.eu/certificates', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Accept': 'application/json',
      'Content-Type': 'application/json',
      'X-Tenant': TENANT,
    },
    body: JSON.stringify(payload),
  });

  if (!response.ok) {
    const error = await response.json();

    if (response.status === 422) {
      // Erro de validação — inspecione error.errors para detalhes por campo
      console.error('Validation failed:', error.errors);
    } else if (response.status === 401) {
      // Token expirado ou ausente — renove e tente novamente
      await refreshToken();
    } else {
      throw new Error(error.message);
    }
  }

  return response.json();
}

​
Erros comuns

Devolve 401 ou 404 dependendo do endpoint. Inclua sempre X-Tenant nos endpoints de recursos.
Ao criar um certificado, o file_uuid deve referenciar um ficheiro que ainda não foi associado a outro certificado. Os ficheiros registam um timestamp used_at — uma vez definido, o ficheiro não pode ser reutilizado.
Todos os campos UUID devem estar no formato padrão v4: 550e8400-e29b-41d4-a716-446655440000. Passar um ID inteiro onde um UUID é esperado devolve 422.
Se passar um course_uuid ou student_uuid que pertence a um tenant diferente, a API devolve 422 com "The selected ... is invalid." — a procura de entidades é sempre filtrada por tenant.