Erros
Toda resposta de erro é application/problem+json (RFC 9457):
{ "type": "https://…/docs/erros#gasto_nao_confirmado", "title": "Gasto não confirmado", "status": 409, "code": "gasto_nao_confirmado", "detail": "…", "instance": "/api/v1/pesquisas" }Decida pelo code — é o contrato estável. title e detail são para gente ler. A tabela abaixo é gerada do mesmo código que o servidor usa.
| Status | code | Quando acontece | O que fazer |
|---|---|---|---|
| 401 | chave_invalida | A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito. | Crie uma chave nova em Conta → API e MCP e troque no cliente. |
| 401 | sem_sessao | A rota aceita só sessão do app (cookie) e a request veio sem ela. | Entre no app e tente de novo. Chave de API não serve nesta rota. |
| 403 | so_sessao | A rota é de gestão da própria chave (criar, listar, revogar) e foi chamada com chave de API — chave não cria chave. | Use a tela Conta → API e MCP. |
| 403 | escopo_insuficiente | A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao). | Crie uma chave com o escopo marcado. Escopos não mudam depois de criados. |
| 403 | cross_site | Request com sessão vinda de outro site por script (fetch/XHR). Só o próprio app pode usar a sessão. | Integrações de fora usam chave de API, não a sessão. |
| 400 | corpo_invalido | O JSON não é válido ou não passa na validação do campo (o detail diz qual). | Corrija o campo apontado. O schema de cada rota está em /docs/api. |
| 400 | parametro_invalido | Um parâmetro de caminho ou de query está fora do formato (id, cursor, data). | Confira o formato em /docs/api. |
| 405 | metodo_nao_permitido | A rota existe, mas não com este método HTTP. | Use o método do header Allow. |
| 404 | nao_encontrado | O recurso não existe — ou pertence a outro workspace, que responde igual (não revelamos que o id é válido). | Confira o id. Liste o recurso para ver os que são seus. |
| 400 | confirmacao_ausente | Publicar e responder agem na conta de um terceiro e exigem confirmar: true literal no corpo. | Mostre à pessoa o que vai acontecer e, com o sim dela, repita com confirmar: true. |
| 409 | gasto_nao_confirmado | A rota cobra da conta (fonte ou IA) e o corpo não trouxe confirmarGasto: true. O detail diz o valor. | Diga à pessoa o valor e, com o sim dela, repita com confirmarGasto: true. |
| 409 | teto_do_mes | A chamada estouraria o teto de gasto do mês configurado em Conta → Custo. | Suba o teto (PUT /v1/custo/teto) ou espere o mês virar. |
| 409 | limite_do_plano | O plano do workspace (Grátis, Pro ou Agência) não comporta mais um deste recurso — nichos, posts, criações, marcas, concorrentes — ou não inclui a ação (publicar no Grátis). O detail diz o uso, o limite e o plano que destrava. | Mostre a frase à pessoa. O plano se troca em Conta → Plano no app; a API não assina. |
| 429 | limite_excedido | A chave passou do limite da classe (ver /docs/limites). Retry-After diz quantos segundos esperar. | Espere o Retry-After. Leituras repetidas cabem em cache do seu lado. |
| 400 | idempotencia_invalida | O header veio vazio ou com mais de 200 caracteres. | Mande um UUID por operação. |
| 400 | recusado | O motor de publicação recusou antes de tocar a rede (falta de confirmação explícita ou peça inválida). O detail diz o motivo. | Leia o detail; em geral é repetir com confirmar: true. |
| 404 | peca_desconhecida | A peça não existe ou é de outro workspace. | Liste as peças (GET /v1/pecas). |
| 409 | peca_nao_e_rascunho | Editar só vale para rascunho; a peça já é compromisso no calendário. | Cancele (DELETE) e crie outra, ou publique. |
| 409 | sem_midia | A peça não tem imagem/vídeo acessível pelo servidor; a rede não aceita post sem mídia. | Prepare a mídia pela tela (Conteúdo → peça) e tente de novo. |
| 409 | sem_conta | O workspace não tem conta da rede conectada e ativa. | POST /v1/conexoes/{rede} devolve a URL para conectar. |
| 409 | ponte_nao_configurada | A chave da ponte de publicação não está no ambiente. | É do operador do Pico, não seu. Avise o suporte. |
| 409 | em_andamento | A peça já está sendo publicada por outra chamada. | Consulte GET /v1/pecas/{id} em alguns segundos. |
| 200 | ja_publicado | A peça já tinha sido publicada; nada foi feito de novo. | Nada. O permalink vem na resposta. |
| 429 | adiado | O teto de publicações/interações da conta na rede foi atingido; o cron tenta depois. | Espere. GET /v1/pecas/{id} mostra quando saiu. |
| 502 | falhou | A rede/ponte respondeu erro. O detail traz o motivo e o requestId para o suporte. | Tente de novo mais tarde; se persistir, mande o requestId. |
| 429 | cota_esgotada | A conta gastou as interações do período na rede. | Espere o período virar. |
| 409 | janela_fechada | Passaram 7 dias do comentário (private reply) ou 24 h da última DM: a rede não aceita mais resposta. | Nada a fazer por este canal; o lead pode ser contatado por outro meio. |
| 409 | ja_respondido | Este lead já recebeu resposta (a rede permite 1 private reply por comentário). | Nada. |
| 400 | canal_invalido | O lead não é de comentário nem de DM respondível. | Veja channel em GET /v1/leads. |
| 409 | sem_post | O comentário é de um post que o Pico não conhece. | Responda pela rede. |
| 409 | sem_conversa | A DM não tem conversa aberta na ponte. | Responda pela rede. |
| 409 | pesquisa_em_andamento | O resultado pedido ainda não existe: a pesquisa está rodando. | Consulte GET /v1/pesquisas/{id} até status: completed. |
| 400 | kind_nao_publica | Brief e lista de ganchos não vão para o calendário. | Use-os no roteiro ou no carrossel. |
| 409 | conexao_recusada | A ponte de publicação não iniciou a conexão da rede (limite de perfis do plano, brand inválida, ponte fora). O detail traz o motivo e codigoDaPonte o código dela. | Se for limite de perfis, é do operador do Pico. Senão, tente de novo mais tarde. |
| 403 | termo_pendente | A pessoa dona da chave ainda não aceitou o termo de conexão de contas (versão vigente) no app. | Abra o Pico em Ajustes › Conexões, conecte uma rede pela tela uma vez (o termo aparece lá) e tente de novo. |
| 400 | rede_invalida | A rede não é instagram, tiktok ou youtube. | Use uma das três. |
| 502 | ia_indisponivel | O provedor de IA falhou ou está sem crédito. | Tente mais tarde. Se persistir, é do operador do Pico. |
| 502 | fonte_indisponivel | A fonte falhou ou a chave dela está ausente/sem saldo. | Tente mais tarde. Se persistir, é do operador do Pico. |
| 500 | erro_interno | Algo quebrou do nosso lado. O detalhe foi para o log, não para cá. | Tente de novo. Se persistir, mande a hora e a rota. |
Por rota
Cada rota lista os erros que pode devolver na referência. Os comuns a todas (com chave): chave_invalida, sem_sessao, escopo_insuficiente, limite_excedido, erro_interno.
API do Pico · versão 2026-09-11 · changelog · privacidade