> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dokstamp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tratamento de Erros

> Compreenda os códigos de estado HTTP e a estrutura de resposta de erro devolvida pela API.

# 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ódigo | Significado           | Causa comum                                   |
| ------ | --------------------- | --------------------------------------------- |
| `200`  | OK                    | Pedido bem-sucedido                           |
| `201`  | Created               | Recurso foi criado                            |
| `204`  | No Content            | Recurso foi eliminado                         |
| `400`  | Bad Request           | Corpo do pedido malformado                    |
| `401`  | Unauthorized          | Header `Authorization` ausente ou inválido    |
| `403`  | Forbidden             | Token válido, mas sem permissões suficientes  |
| `404`  | Not Found             | Recurso não existe ou pertence a outro tenant |
| `422`  | Unprocessable Entity  | Validação falhou (consulte o campo `errors`)  |
| `429`  | Too Many Requests     | Limite de taxa excedido                       |
| `500`  | Internal Server Error | Erro inesperado no servidor                   |

***

## Corpo da resposta de erro

Todas as respostas de erro devolvem um corpo JSON com `success: false`. A estrutura varia consoante o tipo de erro.

### Erro de validação (422)

```json theme={null}
{
  "success": false,
  "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)

```json theme={null}
{
  "success": false,
  "message": "Unauthenticated."
}
```

### Não encontrado (404)

```json theme={null}
{
  "success": false,
  "message": "Resource not found."
}
```

### Erro genérico do servidor (500)

```json theme={null}
{
  "success": false,
  "message": "Server Error"
}
```

***

## Tratando erros no código

<CodeGroup>
  ```javascript JavaScript theme={null}
  async function createCertificate(payload) {
    const response = await fetch('https://api.dokstamp.com/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 — solicite um novo token de serviço
        await renewToken();
      } else {
        throw new Error(error.message);
      }
    }

    return response.json();
  }
  ```

  ```php PHP theme={null}
  use Illuminate\Support\Facades\Http;

  $response = Http::withToken($token)
      ->withHeaders(['X-Tenant' => $tenant, 'Accept' => 'application/json'])
      ->post('https://api.dokstamp.com/certificates', $payload);

  if ($response->failed()) {
      $error = $response->json();

      if ($response->status() === 422) {
          // Erros de validação por campo
          foreach ($error['errors'] as $field => $messages) {
              logger()->warning("$field: " . implode(', ', $messages));
          }
      }

      throw new RuntimeException($error['message'] ?? 'API error');
  }

  $certificate = $response->json('data');
  ```
</CodeGroup>

***

## Erros comuns

<AccordionGroup>
  <Accordion title="Header X-Tenant ausente">
    Devolve `401` ou `404` dependendo do endpoint. Inclua sempre `X-Tenant` nos endpoints de recursos.
  </Accordion>

  <Accordion title="Ficheiro já em uso">
    Ao criar um certificado, o `file_uuid` deve referenciar um ficheiro que ainda não foi associado a outro certificado. Uma vez que um ficheiro é utilizado, não pode ser reutilizado.
  </Accordion>

  <Accordion title="Formato de UUID incorreto">
    Todos os campos UUID devem estar no formato padrão v4: `550e8400-e29b-41d4-a716-446655440000`. Passar um inteiro onde um UUID é esperado devolve `422`.
  </Accordion>

  <Accordion title="Referenciando entidades de outro tenant">
    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.
  </Accordion>
</AccordionGroup>