# Saída de erro estruturada na AWS CLI
<a name="cli-usage-error-format"></a>

Este tópico descreve os formatos de saída de erro estruturada para a AWS Command Line Interface (AWS CLI). A CLI grava erros em stderr e aceita os seguintes formatos:
+ **[`enhanced`](#cli-error-format-enhanced)** (padrão): mensagem de erro com detalhes adicionais exibidos em linha. Use para depuração legível por humanos.
+ **[`json`](#cli-error-format-json)**: a saída é formatada como uma string [JSON](https://json.org/) com todos os campos de erro. Use para automação e criação de scripts.
+ **[`yaml`](#cli-error-format-yaml)**: a saída é formatada como uma string [YAML](https://yaml.org/) com todos os campos de erro. Use para automação e criação de scripts.
+ **[`text`](#cli-error-format-text)**: formata erros usando o formatador de texto. Use para verificação visual rápida.
+ **[`table`](#cli-error-format-table)**: formata erros usando o formatador de tabela. Use para verificação visual rápida.
+ **[`legacy`](#cli-error-format-legacy)**: formato de erro original sem detalhes estruturados. Use para compatibilidade com versões anteriores.

## Configurar o formato do erro
<a name="cli-error-format-configuring"></a>

É possível configurar o formato do erro usando qualquer um dos seguintes métodos:

Sinalizador da linha de comandos  

```
$ aws <command> --cli-error-format json
```

Arquivo de configuração: (`~/.aws/config`)  

```
[default]
cli_error_format = json
```

Variável de ambiente  

```
$ export AWS_CLI_ERROR_FORMAT=yaml
```

## Formato de saída de erro
<a name="cli-error-output-formats"></a>

As seguintes seções descrevem cada formato.

### Formato aprimorado (padrão)
<a name="cli-error-format-enhanced"></a>

O formato aprimorado exibe mensagens de erro com detalhes adicionais em linha para valores simples. Para estruturas complexas, o formato fornece uma dica para usar JSON ou YAML.

**Exemplo: configuração de região ausente**

```
aws: [ERROR]: An error occurred (NoRegion): You must specify a region. You can also configure your region by running "aws configure".
```

**Exemplo: bucket do S3 inexistente com campos adicionais**

```
aws: [ERROR]: An error occurred (NoSuchBucket) when calling the GetObject operation: The specified bucket does not exist

Additional error details:
BucketName: amzn-s3-demo-bucket
```

**Exemplo: campos de erro complexos**

```
An error occurred (TransactionCanceledException) when calling the TransactWriteItems operation: Transaction cancelled, please refer cancellation reasons for specific reasons [ConditionalCheckFailed, None]

Additional error details:
CancellationReasons: <complex value>
Use "--cli-error-format json" or another error format to see the full details.
```

### Formato JSON
<a name="cli-error-format-json"></a>

O formato JSON fornece uma representação estruturada com todos os campos de erro.

**Exemplo: configuração de região ausente**

```
{
    "Code": "NoRegion",
    "Message": "You must specify a region. You can also configure your region by running \"aws configure\"."
}
```

**Exemplo: bucket do S3 inexistente**

```
{
    "Code": "NoSuchBucket",
    "Message": "The specified bucket does not exist",
    "BucketName": "amzn-s3-demo-bucket"
}
```

### Formato YAML
<a name="cli-error-format-yaml"></a>

O formato YAML fornece uma representação estruturada com todos os campos de erro.

**Exemplo: configuração de região ausente**

```
Code: NoRegion
Message: You must specify a region. You can also configure your region by running "aws configure".
```

**Exemplo: bucket do S3 inexistente**

```
Code: NoSuchBucket
Message: The specified bucket does not exist
BucketName: amzn-s3-demo-bucket
```

### Formato de texto
<a name="cli-error-format-text"></a>

O formato de texto usa o mesmo formatador usado para uma saída bem-sucedida do comando.

**Exemplo: bucket do S3 inexistente**

```
amzn-s3-demo-bucket  NoSuchBucket    The specified bucket does not exist
```

### Formato da tabela
<a name="cli-error-format-table"></a>

O formato de tabela usa o mesmo formatador usado para uma saída bem-sucedida do comando.

**Exemplo: bucket do S3 inexistente**

```
-------------------------------------------------------------------------------------|
|                                       error                                        |
+---------------------------+---------------+----------------------------------------+
|        BucketName         |     Code      |                Message                 |
+---------------------------+---------------+----------------------------------------+
|  amzn-s3-demo-bucket      |  NoSuchBucket |  The specified bucket does not exist   |
+---------------------------+---------------+----------------------------------------+
```

### Formato legado
<a name="cli-error-format-legacy"></a>

O formato legado fornece o formato de erro original sem detalhes estruturados. Esse formato não inclui o prefixo “An error occurred (ErrorCode):” para exceções da CLI.

**Exemplo: configuração de região ausente**

```
aws: [ERROR]: You must specify a region. You can also configure your region by running "aws configure".
```

**Exemplo: bucket do S3 inexistente**

```
An error occurred (NoSuchBucket) when calling the GetObject operation: The specified bucket does not exist
```

**nota**  
Agora os erros incluem consistentemente o prefixo `aws: [ERROR]:` para exceções da CLI. As versões anteriores nem sempre incluíam esse prefixo.  
As seguintes exceções sempre usam o formato legado, independentemente do formato de erro configurado:  
`UnknownArgumentError`: exibe informações de uso.
Interrupções do teclado (`KeyboardInterrupt`)

## Exemplo completo
<a name="cli-error-format-example"></a>

O seguinte exemplo mostra um comando com a formatação de erro JSON.

```
$ aws s3api get-object \
    --bucket amzn-s3-demo-bucket \
    --key file.txt out.txt \
    --cli-error-format json
```

Saída (stderr):

```
{
    "Code": "NoSuchBucket",
    "Message": "The specified bucket does not exist",
    "BucketName": "amzn-s3-demo-bucket"
}
```

O campo `BucketName` é um membro de erro modelado exibido pelo serviço Amazon S3.