# Estratégia de Tratamento de Erros

## Fluxo de Erros

```mermaid
sequenceDiagram
    actor User
    participant Frontend
    participant API
    participant External

    User->>Frontend: Ação
    Frontend->>API: Request
    API->>External: Request externo

    alt Sucesso
        External->>API: Success
        API->>Frontend: Success
        Frontend->>User: Feedback sucesso
    else Erro
        External->>API: Error
        API->>API: Catch + Log
        API->>Frontend: Erro formatado
        Frontend->>User: Toast erro
    end
```

## Formato de Resposta de Erro

```typescript
interface ApiError {
  error: {
    code: string;
    message: string;
    details?: Record<string, any>;
    timestamp: string;
    requestId: string;
  };
}
```

## Tratamento de Erros Frontend

```typescript
// lib/error-handler.ts
export function handleApiError(error: unknown): string {
  if (error instanceof ApiClientError) {
    const messages: Record<string, string> = {
      'UNAUTHORIZED': 'Sessão expirada. Faça login novamente.',
      'INSTANCE_NOT_FOUND': 'Instância não encontrada.',
    };
    return messages[error.code] || error.message;
  }
  return 'Erro inesperado. Tente novamente.';
}
```

## Tratamento de Erros Backend

```typescript
// lib/error-handler.ts
export function handleRouteError(error: unknown, requestId: string): NextResponse {
  console.error('[API Error]', { error, requestId });

  if (error instanceof AppError) {
    return NextResponse.json(
      {
        error: {
          code: error.code,
          message: error.message,
          timestamp: new Date().toISOString(),
          requestId,
        },
      },
      { status: error.statusCode }
    );
  }

  return NextResponse.json(
    {
      error: {
        code: 'INTERNAL_ERROR',
        message: 'Erro interno do servidor.',
        timestamp: new Date().toISOString(),
        requestId,
      },
    },
    { status: 500 }
  );
}
```

---