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

# Erros

> Interprete respostas, limites e falhas de validação.

Respostas de erro usam o mesmo envelope JSON. O código é estável para tratamento programático; a mensagem explica a falha. Toda resposta inclui `X-Request-Id`.

```json theme={null}
{
  "error": {
    "code": "unknown_parameter",
    "doc_url": null,
    "message": "This parameter cannot be updated",
    "param": "status",
    "type": "invalid_request_error"
  }
}
```

| Campo | Significado |
| - | - |
| `code` | Código da falha, como `unknown_parameter` ou `resource_not_found`. |
| `doc_url` | Link específico da falha quando disponível; atualmente `null`. |
| `message` | Explicação da falha. Não use o texto como condição do programa. |
| `param` | Parâmetro associado ao erro, ou `null`. |
| `type` | `invalid_request_error`, `authentication_error`, `permission_error`, `rate_limit_error` ou `api_error`. |

## Status HTTP

| HTTP | Como tratar |
| - | - |
| 400 | Corrija o JSON, parâmetros, referências ou condições do objeto. |
| 401 | Confira a chave, sua validade e a forma de autenticação aceita. |
| 403 | Confira as permissões e o acesso à conta. |
| 404 | Confira a rota, o ID e se o objeto pertence à conta. |
| 405 | O método não é aceito nesse caminho; consulte o cabeçalho `Allow`. |
| 409 | Existe conflito de registros ou outra operação com a mesma chave em andamento. |
| 429 | O limite da conta foi atingido. Aguarde o período de `Retry-After`. |
| 500, 502, 503 | Falha de execução ou indisponibilidade. Ao repetir uma escrita, preserve a chave de idempotência. |

## Falhas comuns

| Código | Causa / ação |
| - | - |
| `invalid_body` | O corpo precisa ser um objeto JSON válido. |
| `missing_parameter` | Falta um campo obrigatório. |
| `unknown_parameter` | O campo não é aceito pela operação. |
| `empty_update` | Envie pelo menos um campo editável. |
| `invalid_parameter` | Tipo, valor ou combinação de campos inválida. |
| `price_immutable` | O preço já foi usado; edite apenas nome, ativação e metadados. |
| `resource_in_use` | O registro tem vínculos que impedem a operação ou a referência não está disponível. |
| `resource_conflict` | Já existe um registro com aqueles valores. |
| `invalid_cursor` | O cursor não corresponde à conta, ao recurso ou aos filtros. |
| `idempotency_key_mismatch` | A chave já foi usada com outra operação ou parâmetros. |
| `idempotency_key_in_use` | Outra execução está em andamento; aguarde antes de repetir. |

## Limite de chamadas

O limite é de **300 chamadas por minuto por conta**, compartilhado entre as chaves e as chamadas autenticadas dessa conta. Ao atingir o limite, a resposta `429` informa `Retry-After: 60`.

## Investigar uma chamada

Guarde data, método, rota, status e `X-Request-Id`. Não registre o segredo da chave nem o conteúdo privado do cliente. Falhas de servidor retornam uma mensagem genérica para não expor informações internas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.