Além dos erros específicos relativos ao contexto de negócio, os endpoints podem apresentar erros considerados comuns entre as requisições nas APIs.

Tratam-se de erros cujos status codes, códigos e descrições possuem uma forma fixa que sinalizam comportamentos irregulares já mapeados nos sistemas.

Erros comuns

Status CodeCódigoDescriçãoObservações
400INVALID_PARAMETERO conteúdo da requisição não está de acordo com o esperado.É retornado o header x-bkly-correlation-id relacionado à requisição. O body desse tipo de erro contém um padrão de mensagens que indicarão o parâmetro inválido causador do erro.
401UNAUTHORIZEDSolicitação não autorizada.---
403FORBIDDENO acesso ao recurso foi negado pelo servidor.Este erro pode apresentar códigos e mensagens específicas associados ao certificado tls.
404NOT_FOUNDRecurso não encontrado.É retornado o header x-bkly-correlation-id relacionado à requisição.
405METHOD_NOT_ALLOWEDRecurso acessado com método não suportado.---
406NOT_ACCEPTABLEA solicitação contém um cabeçalho Accept diferente dos tipos de mídia permitidos ou um conjunto de caracteres diferente de UTF-8.---
409CONFLICTA sintaxe da requisição é válida, mas o recurso acessado está em um estado que não pode ser alterado ou já houve um processamento semelhante em andamento.É retornado o header x-bkly-correlation-id relacionado à requisição.
410GONEO recurso está intencionalmente indisponível e esse estado é definitivo.---
415UNSUPPORTED_MEDIA_TYPEFormato de payload não suportado.---
422UNPROCESSABLESintaxe válida, mas a requisição não pode ser processada, devido a uma regra de negócio.É retornado o header x-bkly-correlation-id relacionado à requisição.
429TOO_MANY_REQUESTSA operação foi recusada, pois muitas solicitações foram feitas dentro de um determinado período ou o limite global de requisições concorrentes foi atingido.---
500INTERNAL_SERVER_ERRORErro crítico no servidor que impede o processamento da requisição.É retornado o header x-bkly-correlation-id. Este erro pode apresentar códigos e mensagens específicas associados ao certificado tls.
503SERVICE_UNAVAILABLEErro crítico no servidor que impede o processamento da requisição.É retornado o header x-bkly-correlation-id, assim como o header Retry-After, que indica o tempo em segundos durante o qual o serviço deve ficar indisponível.

🚧

Importante

Os códigos e mensagens dos erros 422 variam de acordo com a regra de negócio que ferem. Portanto, são detalhados nas páginas deste manual que documentam os endpoints.

Erro 400

Embora faça parte da lista de erros comuns, o erro 400 - INVALID_PARAMETER pode conter mensagens variáveis com o objetivo de auxiliar o usuário a identificar um campo faltante ou que apresente valor incorreto.

Na tabela a seguir, veja as possíveis mensagens que sua API poderá receber dentro de um erro 400:

MensagensDescrição
‘{parâmetro}’ must not be empty.Indicação de que determinado parâmetro não pode ser enviado com valor vazio.
‘{parâmetro}’ must be greater than '{valor}'.Indicação de que determinado parâmetro precisa apresentar um valor maior que outro valor especificado na mensagem.
‘{parâmetro}’ must be equal to '{valor}'.Indicação de que determinado parâmetro precisa apresentar um valor igual a outro valor especificado na mensagem.
The ‘{parâmetro}’ field is required.Indicação de que determinado parâmetro é obrigatório.
‘{parâmetro}’ header is required for this request.Indicação de que determinado parâmetro do header é obrigatório.
‘{parâmetro}’ must be in '{valor}' format.Indicação de que determinado parâmetro precisa ser enviado em um formato especificado na mensagem.
'{parâmetro}' it's not allowed to include special characters in this property.Indicação de que não é permitido incluir caracteres especiais no parâmetro especificado.
The length of ‘{parâmetro}’ must be '{valor}' characters or fewer. You entered '{valor}' characters.Indicação do total de caracteres máximo que um parâmetro deve apresentar.

Note que os termos entre chaves { } representam as palavras que poderão variar nas mensagens, correspondendo ao parâmetro ou valor informado de maneira equivocada.

Exemplo:

{
   "errors": [
      {
         "code": "INVALID_PARAMETER",
         "propertyName": "motherName",
         "message": [
            "motherName must not be empty."
         ]
      },
      {
         "code": "INVALID_PARAMETER",
         "propertyName": "documentNumber",
         "message": [
            "The documentNumber field is required."
         ]
      }
   ],
   "reference": "link"
}

📘

Nota

Para evitar a ocorrência de erros 400, siga as instruções de preenchimento dos campos disponíveis na documentação correspondente a cada endpoint.

Erros associados ao certificado TLS

Status CodeCódigoMensagemDescrição
403CLIENT_CERTIFICATE_WAS_REVOKEDClient certificate was revoked.O certificado do client foi revogado. Entre em contato com o Bankly.
403CLIENT_CERTIFICATE_NOT_PRESENTEDClient certificate not presented or called route has no mtls policy.Tentativa de acesso ao recurso sem apresentar o certificado mTLS, necessário para autenticação.
403CLIENT_CERTIFICATE_IS_UNKNOWNClient certificate is unknown.O certificado do client apresentado durante uma tentativa de conexão não é reconhecido ou não é válido para autenticação.
403CLIENT_CERTIFICATE_IS_INVALIDClient certificate is invalid.O certificado do client fornecido durante a tentativa de conexão não atende aos critérios de validade ou integridade exigidos para realizar a autenticação.
403CLIENT_CERTIFICATE_ID_IS_UNKNOWNClient certificate subject DN doesn't have a defined organization unit name (OU) as partner identification.O identificador associado ao certificado do client apresentado durante a tentativa de conexão não é reconhecido ou não corresponde a um ID válido para autenticação.
403CLIENT_CERTIFICATE_HAS_EXPIREDClient certificate has expired.O certificado do client expirou. O parceiro deverá emitir um novo certificado.
403CLIENT_AUTHENTICATION_IS_REQUIREDtls client authentication is required.A autenticação do client é obrigatória para acessar o recurso solicitado.
500CLIENT_AUTHENTICATION_FAILUREUnknown tls client authentication failure.Ocorreu um erro desconhecido referente à autenticação tls de client.