Corpo do erro#
Todo erro, em todo endpoint, tem esta forma:
| Campo | Significado |
|---|---|
code | O status HTTP, repetido. Sempre presente. |
message | Uma frase para uma pessoa. Sempre presente; não estável. |
codeDescription | Um identificador estável para o erro específico, quando o endpoint distingue vários. Baseie-se nisso, não em message. |
data | Detalhe extra para alguns erros — por exemplo, os Items que já existem ao criar um que duplicaria uma conexão. |
Códigos de status#
| Status | Significado | Geralmente por causa de |
|---|---|---|
400 Bad Request | A solicitação é inválida. | Um campo ausente ou malformado. |
401 Unauthorized | A credencial está ausente, errada ou expirada. | Uma API Key que passou de 2 horas, ou clientId/clientSecret errados em POST /auth (CLIENT_KEYS_UNAUTHORIZED, CLIENT_DISABLED). |
403 Forbidden | A credencial não pode acessar este recurso. | Um Connect Token usado fora de seu escopo — veja AutenticaçãoAPI. |
404 Not Found | Nenhum recurso desse tipo. | Um id que não existe. |
405 Method Not Allowed | O endpoint não suporta este verbo. | |
406 Not Acceptable | Um formato diferente de JSON foi solicitado. | |
409 Conflict | A solicitação contradiz o estado atual do recurso. | Um conflito ao atualizar um Item — veja PATCH /items/{id}API. |
429 Too Many Requests | Um limite de taxa foi excedido. | Veja Limites de TaxaAPI para os limites e o cabeçalho Retry-After. |
500 Internal Server Error | Algo falhou do nosso lado. | Tente novamente mais tarde. |
503 Service Unavailable | Temporariamente offline para manutenção. | Tente novamente mais tarde. |
A página de cada endpoint nesta referência lista os status que ele retorna e, onde a API os distingue, os valores de codeDescription.
Criando e atualizando um Item#
Esses retornam de POST /itemsAPI e
PATCH /items/{id}API. Onde o texto abaixo mostra um
:placeholder, a mensagem real carrega o valor — uma frequência, uma espera, um
nome de parâmetro.
codeDescription | Status | Mensagem | O que fazer |
|---|---|---|---|
PARAMETERS_NOT_PROVIDED | 400 | parâmetros não foram fornecidos | Envie as credenciais da conexão para sincronizar o item. |
ITEM_ALREADY_UPDATING | 400 | Uma atualização já está em andamento, aguarde até que a última execução termine | Este item está sincronizando. Aguarde a execução terminar — sucesso ou erro — antes de acionar outra. |
ITEM_IS_ALREADY_UPDATING | 400 | Há um item ativo para o conjunto de credenciais que não terminou de executar | O mesmo conjunto de credenciais está sincronizando em outro item. Aguarde por ele, para que duas sessões não sejam abertas com a instituição ao mesmo tempo. |
CLIENT_IS_UPDATING_BEFORE_ALLOWED_FREQUENCY | 409 | Atualizações do cliente neste item são permitidas no máximo a cada :minUpdateFrequencyAllowedInHours horas. A última atualização foi em :lastUpdatedAt | Aguarde até que a frequência mínima tenha passado desde a última atualização. O limite é por equipe e ajustável — pergunte ao suporte se seu caso de uso precisar de um mais curto. |
LAST_EXECUTION_HAD_LOGIN_ERROR | 400 | A última execução teve um erro de login, você deve atualizar os parâmetros | A última sincronização falhou ao fazer login. Envie novas credenciais antes de atualizar novamente. |
TOO_MANY_CONSECUTIVE_LOGIN_FAILURES | 400 | deve aguardar pelo menos :readableBackoffTime após :maxConsecutiveFailedLoginAttempts erros de login consecutivos, a última tentativa foi em :lastExecutionEndedAt (pode tentar novamente após: :canRetryAfterDate) | Um cooldown após erros de login repetidos, para que a conta do usuário não seja bloqueada pela instituição. Tente novamente após o tempo na mensagem. |
TOO_MANY_CONSECUTIVE_ERRORS | 400 | Houve mais de 5 sincronizações falhadas, entre em contato com o suporte | A conexão falhou muitas vezes seguidas. Relate ao suporte com o itemId. |
ITEM_IN_ERROR_COOLDOWN | 409 | Este conjunto de credenciais falhou recentemente ao conectar e está em um período de cooldown, por favor, tente novamente mais tarde | Essas credenciais falharam recentemente e estão em um cooldown. Tente novamente após passar. |
CONNECTOR_OFFLINE | 409 | este conector está offline neste momento | O conector não está aceitando execuções agora. Tente novamente mais tarde — veja status.pluggy.ai. |
CONNECTOR_REQUIRED_PARAMETER_VALIDATION_ERROR | 400 | O parâmetro :parameter é necessário para ser renovado para a atualização do item. | O conector agora requer esse parâmetro novamente. Envie-o para atualizar a conexão. |
ITEM_ORIGINAL_CONNECTED_WITH_DIFFERENT_ACCOUNT | 409 | O Item foi originalmente conectado com uma conta diferente, por favor, use a conta original | As credenciais agora apontam para uma conta diferente da qual o item foi criado. Use a conta original ou crie um novo item. |
ITEM_CREATION_LIMIT_EXCEEDED | 409 | O cliente excedeu o limite de criação de itens (:itemsLimit itens) para o nível de assinatura atual. | Você atingiu o limite de itens da sua assinatura. Exclua itens não utilizados ou entre em contato com o suporte. |
CLIENT_HAS_ITEM_UPDATES_DISABLED | 409 | O cliente tem atualizações de itens desativadas | Atualizações foram desativadas para a equipe. Entre em contato com o suporte. |
CREATE_ITEMS_API_FREE_DISABLED | 400 | A assinatura gratuita só pode criar itens através do nosso Connect Widget | Na assinatura gratuita, os itens são criados através do Connect Widget. |
SANDBOX_CLIENT_ITEM_UPDATE_NOT_ALLOWED | 400 | O nível de assinatura do cliente atual só pode atualizar itens do Sandbox (Pluggy Bank) | Seu nível de assinatura só permite atualizar itens do Sandbox (Pluggy Bank). |
Erros de MFA#
Retornados ao enviar um parâmetro de múltiplos fatores para um Item — veja Atualizando um Item.
codeDescription | Status | Mensagem | O que fazer |
|---|---|---|---|
ITEM_MFA_NOT_FOUND | 404 | item não tem solicitação de entrada mfa | O item não está aguardando uma entrada de MFA, então nenhuma pode ser enviada. |
ITEM_MFA_ALREADY_PROVIDED | 400 | item não tem solicitação de entrada mfa, já foi fornecida | Nada a fazer — o MFA já foi enviado. |
ITEM_MFA_EXPIRED | 400 | O parâmetro MFA do Item expirou, por favor, inicie uma nova atualização | A janela de MFA fechou. Inicie uma nova atualização para sincronizar a conexão. |
ITEM_MFA_PARAMETER_EXPECTED_MISMATCH | 400 | O Item está esperando o nome do parâmetro MFA ':parameter' | O item está aguardando um parâmetro diferente. Use o nome na mensagem. |
MFA_PARAMERTER_WAS_ALREADY_USED_ERROR | 400 | O parâmetro MFA deve ser atualizado da última execução | O valor enviado é o que já foi usado na última execução. Peça ao usuário um novo. |
MFA_PARAMERTER_WAS_ALREADY_USED_ERROR
A grafia não é um erro de digitação nesta página: a API retorna PARAMERTER. Combine exatamente se você ramificar sobre isso.
Leia o guia: Códigos de Erros.