Erros - Hubfy

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.

{
  "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.