Erros

Esta é a lista completa de erros da API da plataforma Kaleidr. Cada erro tem um status HTTP e um código: uma string curta e estável que seu programa pode usar para tomar decisões. O status, por si só, não é suficiente. 403 abrange várias causas diferentes, e 429 pode significar tanto "reduza a frequência" quanto "sua cota acabou".

Comece pelos formatos de resposta, pois o código nem sempre aparece no mesmo campo.

Formatos de resposta

Formato	Exemplo	Utilização
Código encapsulado	{"detail": "origin_not_allowed"}	Quase todos os erros 401, 403, 404, 413, 500 e 503, os códigos de limites de requisição 422 e dois erros 429 (map_load_quota_exceeded e ingest_rate_limited da API de upload). O código é a string detail.
Objeto plano	{"error": "rate_limited", "detail": "API key rate limit exceeded. Slow down."}	Todos os outros erros 429. O código fica em error; detail é uma frase destinada ao usuário. Erros de cota incluem mais campos.
Lista de validação	{"detail": [{"loc": ["body", "product"], "msg": "…", "type": "…"}]}	422 para corpo ou consulta malformados. detail é um array, com uma entrada por problema.
Erro com 200	{"error": "Route planning failed."}	Apenas POST /chat/control/route. Veja abaixo.

Uma função que lê o código de qualquer um desses formatos:

async function kaleidrError(res) {
  const body = await res.json().catch(() => ({}));
  const code =
    typeof body.error === 'string' ? body.error :      // flat 429
    typeof body.detail === 'string' ? body.detail :    // wrapped code
    Array.isArray(body.detail) ? 'validation_error' :  // 422
    'unknown_error';
  return { status: res.status, code, body, retryAfter: Number(res.headers.get('retry-after')) || null };
}

Dois cabeçalhos importam: Retry-After nas respostas 429, em segundos, e X-Request-Id, quando presente, para identificar a requisição ao entrar em contato com o suporte.

Autenticação: 401

A API não aceita as credenciais.

Código	Quando ocorre	O que fazer
Invalid or missing API key	Nenhuma credencial foi enviada, ou a chave é desconhecida, revogada ou expirada. Também ocorre com: token de sessão expirado; sessão cuja chave foi revogada ou rotacionada sem período de carência; sessão cujo origin ou produto foi removido da chave; sessão emitida antes de um downgrade de plano; organização suspensa ou sem plano.	Verifique a chave e o status dela em kaleidr.com/api-keys. Para uma sessão, faça a troca novamente. Se uma chave válida continuar falhando, tente novamente em instantes: uma falha temporária da plataforma também pode gerar essa resposta.
publishable_requires_session	Uma chave publicável (kld_pk_…) foi enviada a um endpoint de execução.	No navegador, deixe o SDK efetuar a troca ou chame POST /sdk/sessions primeiro. No backend, use uma chave de servidor.

Autorização: 403

A API reconhece as credenciais, mas recusa esta requisição.

Código	Quando ocorre	O que fazer
insufficient_scope	A chave foi criada sem o escopo exigido por este endpoint ou produto.	Use uma chave com o escopo. Não é possível adicionar escopos a uma chave existente.
tier_capability_not_allowed	A chave tem o escopo ou produto, mas o plano atual da organização não o inclui. Também é retornado para um mapa publicado quando o plano do proprietário não inclui chat. Não é retornado para vendor: uma chave com vendor em um plano inferior ao Enterprise não é recusada, mas suas respostas são produzidas sem os seus dados.	Altere o plano ou use um produto incluído nele.
server_key_in_browser	Uma chave de servidor (kld_sk_…) foi enviada com um cabeçalho Origin.	Transfira a chamada para o backend. Se a chave estava no código-fonte da página, rotacione-a.
session_origin_mismatch	Um token de sessão foi utilizado em um origin diferente daquele para o qual foi emitido, ou uma sessão de mapa publicado foi usada sem Origin.	Faça a troca da sessão na página que vai utilizá-la.
ip_not_allowed	Uma chave de servidor ou legada com lista de IPs permitidos foi usada de um endereço fora da lista, ou o endereço da origem não pôde ser determinado.	Faça a chamada de um endereço permitido ou altere allowed_ips da chave.
publishable_key_required	POST /sdk/sessions foi chamado com uma chave de servidor ou legada.	Use uma chave publicável na troca.
origin_required	Uma troca de sessão não tinha o cabeçalho Origin.	Faça a troca em uma página do navegador.
origin_not_allowed	O origin da página não está na lista de origens permitidas da chave ou nos domínios permitidos do mapa publicado.	Adicione o origin exato à chave ou o domínio ao mapa.
product_not_allowed	A chave está limitada a determinados produtos e a requisição é para outro. Na troca da sessão: o product solicitado não está entre os produtos permitidos da chave publicável. Em um endpoint de execução: uma chave de servidor ou legada chamou um endpoint de um produto não permitido, como uma chave limitada a tile chamando /chat/*.	Altere allowed_products ou use outra chave.
chat_disabled	Troca de mapa publicado: o Kaleidr AI do mapa não ativa o recurso solicitado.	Ative Control Tower ou Popup Window no bloco Kaleidr AI do mapa no Studio.
feature_not_granted	Uma sessão de mapa publicado aberta para o chat em pop-up foi usada em /chat/control/stream. Cada recurso tem sua própria sessão.	Troque uma sessão com "feature": "control_tower", que o mapa concede enquanto o Control Tower está ativado.
owner_has_no_organization	Troca de mapa publicado: o proprietário do mapa não possui uma organização para receber a cobrança.	O proprietário deve criar uma organização ou participar de uma.

Não encontrado: 404

Código	Quando ocorre	O que fazer
not_found	Troca de mapa publicado: não existe mapa publicado nem link de compartilhamento com este share_id.	Verifique o identificador e se o mapa está publicado.
sessions_disabled	A troca de sessões está desativada na plataforma.	Isso não pode ser alterado por você. Entre em contato com o suporte.
Not Found	O caminho não existe.	Confira a URL em Endpoints, incluindo o prefixo /inference-api/b2b/v1.

Validação: 422

O corpo ou a string de consulta não corresponde ao formato aceito pelo endpoint. detail é um array; em cada entrada, loc indica o campo e msg descreve o problema.

{
  "detail": [
    { "type": "missing", "loc": ["body", "product"], "msg": "Field required", "input": {} }
  ]
}

Corrija a requisição; não tente novamente sem alterá-la. Dois endpoints de streaming, /chat/summary/stream e /chat/button/stream, retornam 500, em vez de 422, para um corpo malformado, exceto quando um campo é longo demais (abaixo).

Limites de solicitação: 422 com código

Uma requisição bem-formada que ultrapassa um limite de tamanho também recebe 422, mas no formato encapsulado: detail contém o código como string, não como array. Nada é cobrado.

{ "detail": "conversation_too_long" }

Código	Endpoint	Quando ocorre	O que fazer
too_many_messages	/chat/control/stream	messages tem mais de 400 entradas.	Envie apenas as interações mais recentes.
message_too_long	/chat/control/stream	O content de uma mensagem ultrapassa 64.000 caracteres.	Reduza a mensagem.
conversation_too_long	/chat/control/stream	A soma de content de todas as mensagens ultrapassa 200.000 caracteres.	Remova as interações mais antigas e envie novamente.
invalid_session_id	/chat/control/stream	session_id tem mais de 128 caracteres ou contém caracteres diferentes de letras, números, _, ., : ou -.	Use um identificador nesse formato, como um UUID.
lang_too_long	/chat/control/stream	lang tem mais de 35 caracteres.	Envie uma tag BCP 47, como pt-BR.
invalid_layout	/chat/control/stream	layout tem mais de 16 caracteres.	Envie guide enquanto o viewer mostra seu layout de guia, ou omita o campo.
field_too_long	/chat/summary/stream, /chat/button/stream	Um campo de texto ultrapassa seu limite ou uma lista tem entradas demais.	Reduza o campo. Os limites estão em Endpoints.

Os limites do fluxo de chat estão em Endpoints.

Solicitação muito grande: 413

Código	Quando ocorre	O que fazer
request_too_large	O corpo da requisição é maior que 2 MiB ou que 5 MiB em um endpoint /design/*. O corpo da resposta é {"detail": "request_too_large"}. Nada é cobrado.	Envie menos dados: reduza a conversa ou as linhas de amostra de uma requisição de design. Não repita o mesmo corpo.
request_body_too_large	Uma requisição às rotas de gerenciamento de chaves ou dados empresariais em /shared-api é maior que 1 MiB, ou maior que 32 MiB no upload POST /shared-api/datahub/ingests.	Envie um corpo menor. Para upload, consulte Enviar seus dados empresariais.

Uma requisição com tamanho declarado muito acima do limite de qualquer endpoint pode ser recusada na borda da rede, antes de chegar à API. Essa resposta não tem corpo JSON Kaleidr e, portanto, não há código para ler: envie menos dados.

Uma requisição recusada pelo tamanho, assim como qualquer requisição recusada antes do processamento, não é cobrada e não ocupa créditos de IA nem uma vaga de concorrência depois disso.

Limites de cota e taxa: 429

Leia o corpo da resposta antes de decidir se deve tentar novamente.

Código	Campo	Retry-After	Quando acontece	O que fazer
quota_exceeded	error	segundos até reset_at	Os créditos de IA da sua organização não são suficientes para cobrir a chamada, ou a chamada ultrapassaria o limite mensal da própria chave. Também é retornado pela chamada de proposta de mapeamento da API de upload.	Não tente novamente. Aguarde até reset_at, adicione créditos ou aumente o limite da chave.
rate_limited	error	5	O limite de solicitações por minuto da chave foi atingido. Também ocorre quando há trocas de sessão demais para uma chave, um mapa publicado ou um endereço.	Aguarde os segundos indicados em Retry-After e tente novamente com um atraso aleatório adicional.
org_overloaded	error	5	Sua organização tem chamadas demais em andamento ao mesmo tempo.	Aguarde uma chamada terminar e tente novamente. Encerre os fluxos de resposta que não forem mais necessários.
b2b_overloaded	error	5	A API atingiu sua capacidade máxima para todos os solicitantes.	Aguarde os segundos indicados em Retry-After e tente novamente com intervalos de espera progressivamente maiores.
limiter_unavailable	error	5	O limitador de taxa não conseguiu responder.	Tente novamente em instantes. O problema não está relacionado à sua taxa de solicitações.
visitor_limit_reached	error	5	Um visitante do chat de um mapa publicado ultrapassou o limite de solicitações por minuto ou por dia.	Oriente o visitante a tentar novamente mais tarde.
map_load_quota_exceeded	detail	nenhum	POST /sdk/sessions para tile: a cota de carregamentos de mapas da organização se esgotou.	Não tente novamente. Aguarde a redefinição do período ou adicione um pacote de carregamentos de mapas.

O corpo de quota_exceeded inclui os números:

{
  "error": "quota_exceeded",
  "detail": "Usage limit reached. Please try again later.",
  "product": "b2b",
  "meter": "b2b.tokens",
  "tier": "pro",
  "limit": 5000000,
  "used": 4999100,
  "remaining": 900,
  "reset_at": "2026-11-01T04:00:00+00:00",
  "period": "month",
  "reset_in_seconds": 1296000
}

Esse é o corpo recebido por uma chave de servidor. Uma requisição com um token de sessão (trocado a partir de uma chave publicável ou de uma sessão de visitante de mapa publicado) recebe um corpo menor, que não revela o plano nem o uso da organização:

{
  "error": "quota_exceeded",
  "detail": "Usage limit reached. Please try again later.",
  "meter": "b2b.tokens",
  "reset_at": "2026-11-01T04:00:00+00:00",
  "reset_in_seconds": 1296000
}

Todos os campos, a variante com limite por chave e o código de tratamento estão em Cotas e limites de taxa.

Erros do servidor: 5xx

Status	Código	Quando ocorre	O que fazer
500	An internal error occurred. Please try again.	Falha inesperada.	Tente mais uma vez depois de uma breve espera.
500	map_design_analyze_failed	POST /design/analyze não conseguiu analisar a tabela. Sem cobrança.	Confira as colunas e linhas de amostra e tente novamente.
500	Summary stream error	POST /chat/summary/stream não conseguiu iniciar: corpo ilegível ou requisição de edifício sem address. Um campo muito longo retorna 422 field_too_long em vez disso.	Corrija o corpo.
500	Button chat stream error	POST /chat/button/stream não conseguiu iniciar: corpo ilegível ou sem query. Um campo muito longo retorna 422 field_too_long em vez disso.	Corrija o corpo.
503	sessions_not_configured	A troca de sessões está indisponível devido a uma falha da plataforma.	Tente novamente; procure o suporte se persistir.
503	share_grant_unavailable	Troca de mapa publicado: não foi possível ler as configurações do mapa.	Tente novamente em instantes.

Erro com status 200

POST /chat/control/route retorna 200 quando não é possível planejar uma rota:

{ "error": "Route planning failed." }

A resposta contém error, sem action. Um cliente que verifica apenas o status interpreta isso como sucesso e depois falha ao ler action. Verifique sempre a presença de error no corpo. O texto foi redigido para ser exibido ao usuário. Detalhes: Rotas.

GET /retrieval/geocode/forward tem um comportamento semelhante: uma busca que falha internamente retorna 200 com a lista results vazia, assim como uma consulta sem correspondências.

Erros em um stream

Tudo acima se aplica antes do início de um fluxo: uma requisição de streaming recusada é um erro HTTP comum. Assim que a resposta é 200 e os quadros começam a chegar, as falhas aparecem como eventos error:

event: error
data: {"type": "error", "code": "upstream_stall", "message": "The AI service stopped responding. Please try again.", "partial_text": "The Louvre sits"}

Fluxo	code	Quando ocorre	O que fazer
/chat/control/stream	upstream_stall	A resposta parou de progredir ou o fluxo atingiu a duração máxima aproximada de 10 minutos.	Ofereça uma nova tentativa. Preserve partial_text caso seja útil.
/chat/control/stream	ausente	Qualquer outra falha durante a resposta.	Exiba message. Uma nova tentativa pode funcionar.
/chat/summary/stream	ausente	O resumo falhou.	Exiba message ou prossiga sem resumo.
/spot/overview/stream	ausente	A visão geral falhou ou a referência ref não pode ser descrita. Nesse caso, o evento inclui ref: uma referência poi: ou region: que não fica no ponto, place: sem hint.name ou um edifício ou endereço, que a API não descreve.	Não exiba visão geral. Não repita um evento que inclua ref.
/chat/button/stream	nenhum	Este fluxo não tem evento error. Uma falha encerra a conexão sem end.	Considere falho um fluxo encerrado sem end.

Regras para todos os fluxos:

• Um evento error substitui end. Depois dele, só pode aparecer um evento quota opcional.
• Uma conexão encerrada sem end nem error falhou.
• O evento quota não é um erro. É um relatório de uso enviado depois de end ou error. Em um fluxo lido com token de sessão, contém apenas type, meter e reset_at.
• Um nome de evento desconhecido não é um erro. Ignore-o.

Um fluxo que falha ou é encerrado antes do fim ainda é cobrado. Em /chat/control/stream, a cobrança nunca é inferior à estimativa da conversa enviada, podendo superar a reserva inicial: consulte Como um fluxo é cobrado. Uma nova tentativa é uma nova requisição, cobrada separadamente.

Erros ocultados pelo navegador

Quando o origin ou a credencial é recusado, a resposta não traz cabeçalho CORS e o navegador oculta o status e o corpo do seu código. A página mostra um erro CORS no console e um fetch rejeitado; o SDK registra um erro contendo [kaleidr:<product>].

Para ler o código real, abra a aba Network e selecione a requisição com falha. Os mais comuns são origin_not_allowed, Invalid or missing API key e server_key_in_browser. Consulte CORS e origens permitidas.

Uma resposta 4xx sem corpo JSON Kaleidr vem da borda da rede, antes da API. É uma limitação de taxa (reduza as chamadas e tente mais tarde) ou uma requisição cujo tamanho declarado supera muito o limite de qualquer endpoint (envie menos dados; repetir a mesma requisição gera a mesma resposta).

Host de tiles

Requisições a tile.kaleidr.com que não venham de uma incorporação Kaleidr com chave publicável válida em um origin permitido recebem:

Status	Código	Retry-After	O que fazer
429	tile_access_restricted (em error, com message e docs)	3600	Use o produto Tile com chave publicável e adicione o origin da página à lista de origens permitidas da chave, se houver.

Gerenciamento de chaves

Erros de https://api.kaleidr.com/shared-api/api-keys, usada pela página API Keys e acessível com o token de acesso da sua conta. Todos usam o formato encapsulado.

Status	Código	Quando ocorre	O que fazer
401	variável	Não há token de acesso de conta válido. Uma chave de plataforma não é aceita aqui.	Faça login novamente.
403	org_admin_required	Sua conta não é de proprietário nem administrador da organização.	Peça ajuda a um proprietário ou administrador.
403	plan_required	A organização não tem um plano.	Escolha um em kaleidr.com/billing.
403	free_plan_publishable_only	Uma chave de servidor foi solicitada no plano Free. Também retornado ao rotacionar chave de servidor ou legada no Free.	Crie uma chave publicável ou mude para Pro.
403	tier_capability_not_allowed	Ao criar chave, scopes ou allowed_products inclui algo não permitido pelo plano. Normalmente, é uma solicitação de vendor no Free ou Pro: recusada mesmo com vendor_acknowledged, e nenhuma chave é criada. Ao editar, allowed_products inclui um produto não permitido ou, no Free, é definido como lista vazia.	vendor exige Enterprise. Caso contrário, informe apenas escopos e produtos permitidos pelo plano.
404	key_not_found	Não há chave com esse identificador na organização. Edição e revogação encontram chaves em qualquer status, portanto revogar uma já revogada retorna 200. Rotação exige chave ativa e retorna esse código para chave revogada.	Confira o identificador. Em uma rotação, a chave pode estar revogada.
409	key_limit_reached	A organização atingiu o limite de chaves ativas do plano (Free 2, Pro 10, Enterprise 25).	Revogue uma chave ou rotacione uma existente em vez de criar outra.
409	key_already_rotated	A chave já foi rotacionada, tenha o período de carência terminado ou não. Não pode ser rotacionada novamente e uma edição que limpe expires_at ou o mova para depois do fim da carência é recusada. Um expires_at anterior e outros campos ainda podem ser editados.	Use a chave substituta.
409	key_expired	Uma chave nunca rotacionada ultrapassou a validade e a edição inclui expires_at. Não é possível renovar a validade de chave expirada, mas seus outros campos ainda podem ser editados.	Crie uma chave nova.
413	request_body_too_large	O corpo da requisição ultrapassa 1 MiB.	Envie um corpo menor.
422	unknown_scope	scopes contém valor diferente de ai, maps, design, vendor.	Corrija a lista.
422	unknown_product	allowed_products contém valor diferente de chat, editor, viewer, tile.	Corrija a lista.
422	vendor_scope_requires_acknowledgement	No Enterprise, foi solicitada chave publicável com vendor sem vendor_acknowledged: true. No Free ou Pro, a mesma requisição retorna 403 tier_capability_not_allowed.	Leia sobre o escopo vendor e envie o campo.
422	no_fields_to_update	Edição sem campo editável.	Envie pelo menos um campo.
422	lista de validação	Origin, IP, validade no passado ou nome malformados.	Corrija o campo indicado em loc.
500	insert_failed, session_unavailable	Falha da plataforma.	Tente novamente.
503	api_key_pepper_not_configured	Criação de chaves indisponível por falha da plataforma.	Tente novamente; procure o suporte se persistir.

Upload de dados empresariais

Erros das rotas de upload em https://api.kaleidr.com/shared-api/datahub e da chamada de proposta de mapeamento. A lista completa, com limites de arquivos e campos por trás de cada 422, está em Enviar seus dados empresariais. Aqui estão os erros que recusam uma requisição antes de ler um arquivo e os erros de despublicação e exclusão de uma versão:

Status	Código	Quando ocorre	O que fazer
403	org_admin_required	A conta não é de proprietário nem administrador da organização. Também retornado pela proposta de mapeamento.	Peça ajuda a um proprietário ou administrador.
403	vendor_data_not_on_plan	O plano da organização não permite upload de dados empresariais. Esse recurso é exclusivo do Enterprise. Retornado por upload, publicação, reprocessamento e proposta de mapeamento. Nunca pelas chamadas de leitura, despublicação ou exclusão.	Mude para Enterprise. GET /shared-api/datahub/limits informa em todos os planos, sem recusar, se a organização pode fazer upload. No Free e Pro, adicione dados a um mapa no Kaleidr Studio: veja Conjuntos de dados em um mapa.
404	release_not_found	Na despublicação ou exclusão, não existe versão com esse identificador na organização, inclusive uma cuja exclusão já terminou.	Em uma exclusão, considere já concluída.
409	org_ingest_in_progress	Outro upload da organização está sendo processado. Retornado por upload, publicação e reprocessamento.	Aguarde terminar e envie novamente.
409	release_not_published	Despublicação de um rascunho ou versão com falha.	Não há nada para despublicar. Exclua-a.
409	release_is_published	Exclusão solicitada para a versão publicada.	Despublique-a e depois exclua.
413	request_body_too_large	A requisição de upload ultrapassa 32 MiB.	Envie um arquivo menor. O arquivo em si pode ter até o limite da organização.
422	{ "errors": [ … ] } em detail	O arquivo excede um limite de linhas ou tamanho, um campo do pacote JSON é longo demais ou o JSON tem aninhamento profundo demais. Um limite contratado menciona o limite e o plano na justificativa.	Leia cada motivo e corrija o arquivo.
429	ingest_rate_limited	A organização iniciou 30 uploads na última hora.	Aguarde e envie novamente.
429	uma frase em detail	A conta fez 30 propostas de mapeamento na última hora. O corpo não tem campo error.	Aguarde e envie novamente.
429	quota_exceeded em error	Proposta de mapeamento: os créditos de IA da organização acabaram. O corpo é a resposta padrão de cota.	Aguarde até reset_at, adicione créditos ou escreva o mapeamento manualmente.

Uploads de conjuntos de dados no Kaleidr Studio

Esta seção não faz parte da API da plataforma autenticada por chave. Ela descreve o que o Kaleidr Studio recebe quando um usuário autenticado adiciona um conjunto de dados a um mapa no painel Data e o upload é recusado pelo tamanho. Nenhuma chave de API está envolvida. Há duas recusas com significados distintos:

Status	Código	Quando ocorre	O que fazer
402	quota_exceeded	Um upload de novo conjunto de dados excede um dos limites do plano da organização: linhas em um conjunto, tamanho de um arquivo ou linhas em todos os conjuntos da organização. limit_key indica o limite. Dados já armazenados permanecem. O Studio exibe a mensagem com link para upgrade.	Envie arquivo menor ou exclua conjuntos desnecessários. No Free, mude para Pro. No Pro ou Enterprise, entre em contato com a Kaleidr para aumentar o total da organização; os limites de linhas por conjunto e tamanho por arquivo não podem ultrapassar os tetos da próxima linha.
400	VALIDATION_ERROR	Arquivo ou conjunto excede um teto válido para todos os planos: arquivo maior que 64 MiB, conjunto com mais de 100.000 linhas, arquivo geográfico com mais de 50.000 feições ou imagem de sobreposição maior que 16 MiB. O código está em error. Mudar de plano não permite esse upload.	Divida o arquivo em outros menores. Não repita o mesmo arquivo e não ofereça upgrade.

A resposta depende do tamanho, não apenas do plano. O teto é verificado primeiro: um arquivo acima de 64 MiB ou conjunto acima de 100.000 linhas retorna 400 no Free, Pro e Enterprise. O 402 é para upload abaixo do teto geral, mas acima do limite da organização; por exemplo, arquivo de 40 MiB no Free, cujo limite é 32 MiB.

402 quota_exceeded

O corpo é um objeto de detalhes do problema que inclui também os campos error e message do Studio. O código aparece em error e code, e a frase aparece em message e detail:

{
  "error": "quota_exceeded",
  "message": "Your plan allows 250,000 rows across all of your organization's datasets. Delete a dataset or upgrade to add more.",
  "type": "https://errors.kaleidr.com/datasets/quota_exceeded",
  "title": "Quota Exceeded",
  "status": 402,
  "detail": "Your plan allows 250,000 rows across all of your organization's datasets. Delete a dataset or upgrade to add more.",
  "code": "quota_exceeded",
  "limit_key": "studio.data.rows.max",
  "limit": 250000,
  "used": 248500,
  "tier": "free",
  "upgrade_url": "https://kaleidr.com/pricing"
}

Campo	Significado
error, code	Sempre quota_exceeded. O mesmo valor duas vezes.
message, detail	A mesma frase duas vezes. Ela descreve o limite em palavras simples e foi escrita para o usuário.
type	Sempre https://errors.kaleidr.com/datasets/quota_exceeded.
title	Sempre Quota Exceeded.
status	Sempre 402.
limit_key	Qual limite recusou o upload. Veja a tabela seguinte.
limit	O limite da organização na unidade correspondente.
used	Para o total, linhas já armazenadas pela organização. Para os outros dois, linhas ou MiB deste upload.
tier	Plano da organização: free, pro ou enterprise. É unknown quando não se pode consultar o plano; nesse caso valem os limites do Free.
upgrade_url	Onde mudar o plano.

limit_key	Limite	Unidade de limit e used	Frase
studio.dataset.rows.max	Linhas em um conjunto de dados	Linhas	"Seu plano permite 50.000 linhas em um conjunto de dados. Envie um arquivo menor ou faça upgrade."
studio.dataset.file.mb	Tamanho de um arquivo enviado	MiB	"Seu plano permite arquivos de até 32 MB. Envie um arquivo menor ou faça upgrade."
studio.data.rows.max	Linhas em todos os conjuntos da organização	Linhas	"Seu plano permite 250.000 linhas em todos os conjuntos da sua organização. Exclua um conjunto ou faça upgrade para adicionar mais."

Os números nas frases são os limites do Free; a frase recebida traz os da sua organização. Mostre-a ao usuário e decida com base em code e limit_key. Esse 402 é diferente do 429 quota_exceeded da API da plataforma, relativo a créditos de IA.

400 VALIDATION_ERROR

O corpo tem dois campos e nenhum membro adicional de detalhes do problema:

{
  "error": "VALIDATION_ERROR",
  "message": "File is larger than 64 MB."
}

Motivo da recusa	message
Arquivo maior que 64 MiB	"O arquivo é maior que 64 MB."
Conjunto com mais de 100.000 linhas	"Máximo de 100000 registros por conjunto de dados"
Arquivo geográfico com mais de 50.000 feições	"<filename> tem mais de 50000 feições. Divida ou simplifique a geometria antes do upload."
Imagem de sobreposição maior que 16 MiB	"A imagem de sobreposição é maior que 16 MB."

O mesmo status e código são retornados para outros problemas com um arquivo enviado, como tipo de arquivo não suportado pelo Studio ou arquivo sem linhas utilizáveis; message indica a causa. Trate qualquer 400 de upload como "este arquivo não pode ser adicionado como está" e exiba message.

Conteúdo relacionado

• Autenticação e escopos: credenciais e troca de sessão.
• Cotas e limites de taxa: detalhes das respostas 429.
• Contrato SSE: eventos de um fluxo.
• Solução de problemas: problemas por sintoma.