Tratamento de erros

O SDK traduz as respostas HTTP de erro em uma hierarquia de exceções tipada, então você trata por tipo em vez de inspecionar status codes na mão. Todas estendem MerxApiException (que por sua vez é RuntimeException — não exige try/catch obrigatório).

Hierarquia

Exceção	Quando	Status HTTP
MerxBadRequestException	Requisição inválida	400
MerxUnauthorizedException	Token ausente/ inválido	401
MerxForbiddenException	Sem permissão	403
MerxNotFoundException	Recurso não existe	404
MerxConflictException	Conflito de estado	409
MerxValidationException	Falha de validação (carrega os erros por campo)	422
MerxServerException	Erro do servidor	5xx
MerxApiException	Qualquer status não mapeado (classe base)	demais
MerxClientException	Falha local (rede, timeout, serialização) — não é resposta HTTP	—

Todas as MerxApiException expõem getStatusCode() e getResponseBody() (corpo cru) para inspeção quando o tipo não basta.

Tratando por tipo

import com.merx.sdk.core.exception.*;

try {
    // operações que mutam (create/update/delete) lançam exceção em erro HTTP
    merx.producers().update(id, request);
} catch (MerxNotFoundException e) {
    // 404 — recurso não existe
} catch (MerxValidationException e) {
    // 422 — erros por campo
    e.getFieldErrors().forEach((campo, msg) -> log.warn("{}: {}", campo, msg));
} catch (MerxApiException e) {
    // qualquer outro erro HTTP
    log.error("Merx {} -> {}", e.getStatusCode(), e.getResponseBody());
} catch (MerxClientException e) {
    // falha de rede/serialização (não chegou resposta)
}

Finders retornam Optional

Métodos de busca não lançam em 404 — retornam Optional.empty(). Use sem try/catch:

merx.producers().findById(id)
    .ifPresentOrElse(
        p -> processa(p),
        () -> log.info("produtor não encontrado"));

Retry automático

Falhas transitórias (5xx, 429, IOException/timeout) já passam por retry com backoff antes de virarem exceção — você só recebe a exceção quando as tentativas se esgotam. Erros 4xx (exceto 429) não são retentados. Veja Configuração avançada.