Erros da API - Base de conhecimento

Erros

Toda requisição que falha devolve o mesmo envelope: um status HTTP e um corpo JSON com um code legível por máquina. Ramifique o código pelo error.code, nunca pelo error.message — os códigos são estáveis, as mensagens não.

O código não repete o status HTTP. 404 Not Found chega com o código 400404; uma requisição sem o cabeçalho Authorization chega com HTTP 400 e código 100101. Leia o status e o código de forma independente.

{
  "error": {
    "code": 400301,
    "message": "invalid uuid format",
    "detail": "see https://en.wikipedia.org/wiki/Universally_unique_identifier"
  }
}

O próprio API devolve esse link. Ele cobre apenas uma das notações aceitas: os caminhos também aceitam um UUID sem hífens e uma forma base58 de 21 a 22 caracteres, então um valor rejeitado com este código não é necessariamente um UUID malformado.

Erros de validação trazem invalid_params, uma entrada por campo rejeitado:

{
  "error": {
    "code": 400400,
    "message": "request parameters didn't validate",
    "invalid_params": [
      { "index": 0, "name": "privacy_type", "reason": "oneof", "message": "anywhere nowhere custom" }
    ]
  }
}

O mesmo código chega sem invalid_params quando falta um parâmetro de consulta obrigatório — nesse caso o nome do parâmetro está dentro de message:

{ "error": { "code": 400400, "message": "Parameter 'from' not found" } }

Erros do servidor usam outro formato: path e timestamp no lugar de detail.

{
  "error": {
    "code": 500500,
    "path": "/v1/videos",
    "message": "no message available",
    "timestamp": "2026-09-24T09:25:48.540408556Z"
  }
}

Um corpo de requisição vazio é relatado à parte, com o código 1 e a mensagem io error.

Campos:

Campo	Tipo	Descrição
`error.code`	`number`	Código legível por máquina. Não repete o status HTTP — a lista completa está abaixo.
`error.message`	`string`	Explicação curta em linguagem natural, adequada para logs. Não é estável: não ramifique por ela.
`error.detail`	`string`	Opcional. Contexto adicional: a posição do erro de JSON, o valor rejeitado ou um link de referência.
`error.invalid_params`	`array`	Opcional. Detalhamento por campo de uma falha de validação. Cada entrada tem `index`, `name` (o campo), `reason` (`required`, `oneof`, `notempty_if`, `not exists`, …) e `message` com os valores aceitos.
`error.path`	`string`	Somente em `5xx`. O caminho que falhou.
`error.timestamp`	`string`	Somente em `5xx`. RFC 3339, UTC.

X-Request-ID. As respostas bem-sucedidas e os erros 400, 401 e 500 trazem este cabeçalho de resposta — informe-o ao acionar o suporte. Ele não é enviado em 404 e 405.

Resumo dos códigos de status HTTP

Código	Nome	Descrição
200	OK	A requisição foi concluída. O corpo da resposta traz o objeto solicitado.
201	Created	O recurso foi criado. O corpo da resposta traz o novo objeto.
204	No Content	A requisição foi concluída; o endpoint não tem corpo a devolver (normalmente após um `DELETE`).
400	Bad Request	Requisição malformada: JSON inválido, identificador que não pôde ser interpretado, valor fora do conjunto permitido. Também é devolvido quando falta o cabeçalho `Authorization` — código `100101`.
401	Unauthorized	O token é inválido, foi revogado ou pertence a outro workspace.
402	Payment Required	O plano ou o saldo não cobrem esta operação. Não reproduzido na verificação.
403	Forbidden	O token está autenticado, mas não tem permissão. Não reproduzido na verificação.
404	Not Found	O objeto não existe ou não é visível para este token. Chega com o código `400404`.
405	Method Not Allowed	O caminho não suporta este método. Chega com o código `400405`.
409	Conflict	Conflito de estado; usado pelo Speak. Não reproduzido na verificação.
422	Unprocessable Entity	O recurso ainda não está pronto; usado pelo Speak. Não reproduzido na verificação.
429	Too Many Requests	Limite de requisições. Não reproduzido: 50 requisições paralelas passaram sem nenhum. O API não envia `RateLimit-*` nem `Retry-After`.
5xx	Server Error	Erro inesperado no servidor. É seguro repetir com backoff exponencial; acione o suporte se persistir.

Códigos numéricos devolvidos em error.code. Um traço na coluna Nome significa que o código ainda não tem um nome legível por máquina — ramifique pelo número. A coluna Repetir indica se repetir a requisição idêntica pode ajudar.

Códigos de autenticação e acesso (1xxxxx)

Código	HTTP	Nome	Repetir	Descrição
1	400	`IO_ERROR`	não	O corpo da requisição não pôde ser lido — normalmente um payload vazio ou truncado, ou uma conexão interrompida.
100101	400	`AUTH_AUTHORIZATION_HEADER_NOT_FOUND`	não	Falta o cabeçalho `Authorization`. Observe o status: `400`, não `401`, e nenhum cabeçalho `WWW-Authenticate` é enviado.
100102	401	`UNAUTHORIZED`	não	O token é inválido, foi revogado ou expirou. A falta do cabeçalho é `100101`. Emita um novo token.
100103	403	`ACCESS_DENIED`	não	O token é válido, mas não dá acesso a este recurso ou escopo. Verifique as permissões do token.
100104	400	`INVALID_USERNAME_OR_PASSWORD`	não	As credenciais enviadas ao endpoint de login não correspondem a nenhuma conta.
100105	400	`INVALID_CONFIRMATION_TOKEN`	não	O token de confirmação de e-mail é desconhecido ou expirou. Solicite um novo.
100106	—	`LIMIT_REACHED`	mais tarde	Uma cota do workspace foi atingida. Verifique o plano.
100107	403	`USER_IS_NOT_OWNER`	não	A ação exige privilégios de proprietário do workspace.

Códigos de requisição inválida e validação (4xxxxx)

Código	HTTP	Nome	Repetir	Descrição
400101	400	`JSON_SYNTAX_ERROR`	não	O corpo da requisição não é um JSON válido. `detail` traz o caractere problemático e seu contexto.
400102	400	`JSON_UNMARSHAL_TYPE_ERROR`	não	Um campo tem tipo inesperado — por exemplo, uma string onde se espera um número.
400201	400	`HAS_ALREADY_BEEN_TAKEN`	não	Uma restrição de unicidade foi violada.
400202	400	`EMAIL_IS_ALREADY_TAKEN`	não	Já existe uma conta com este e-mail.
400203	400	`NAME_IS_ALREADY_TAKEN`	não	Já existe uma entidade com este nome no escopo atual.
400204	400	`INVITATION_IS_ALREADY_EXIST`	não	Um convite já foi enviado a este destinatário.
400205	400	`INVITATION_IS_ALREADY_APPROVED`	não	O convite já foi aceito.
400206	400	`BILLING_ACCOUNT_IS_ALREADY_EXIST`	não	Já existe uma conta de cobrança vinculada a este workspace.
400207	400	`NOT_ENOUGH_MONEY`	mais tarde	O saldo do workspace não cobre esta operação.
400208	400	`NO_BILLING_ACCOUNT`	não	O workspace ainda não tem conta de cobrança.
400209	400	`NO_PAYMENT_METHOD`	não	Nenhuma forma de pagamento está configurada na conta de cobrança.
400210	400	`NOT_ENOUGH_REQUIRED_PRODUCTS`	não	Falta ao plano atual um produto do qual esta operação depende.
400211	400	`NOT_ALLOWED_ADDITIONAL_FOR_TRIAL`	não	Adicionais não podem ser comprados em um plano de teste.
400212	400	`SUBSCRIPTION_NOT_PAID`	mais tarde	O workspace tem faturas em aberto.
400213	400	`EMAIL_NOT_CONFIRMED`	mais tarde	O e-mail do usuário ainda não foi confirmado.
400214	400	`EMAIL_NOT_FOUND`	não	Nenhuma conta está associada ao e-mail informado.
400215	400	`RESET_TOKEN_NOT_FOUND_OR_EXPIRED`	não	O token de redefinição de senha é desconhecido ou expirou.
400216	400	`NOT_ALLOWED_ORDER_FIELD`	não	O parâmetro `order` indica um campo pelo qual este endpoint não ordena. A direção diferencia maiúsculas: `title.DESC` é rejeitado, `title.desc` não.
400236	400	—	não	A pasta referenciada não existe — por exemplo, `parent_id` em Copy video. Traz `invalid_params`; a pasta é verificada antes do vídeo.
400301	400	—	não	O identificador não pôde ser interpretado em nenhuma notação aceita: UUID com hífens, UUID sem hífens ou base58. Não diz nada sobre o objeto existir.
400302	400	—	não	O identificador tem 21–22 caracteres, mas carrega um caractere fora do alfabeto base58 (`O`, `I`, `l`). Um `0` inicial é preenchimento e é aceito; um caractere errado em qualquer outra posição não é.
400400	400	—	não	A validação falhou ou falta um parâmetro de consulta obrigatório. Dois formatos: com `invalid_params` e sem — veja acima.
400404	404	—	não	O objeto não existe ou não é visível para este token. O erro mais comum na prática.
400405	405	—	não	O caminho não suporta este método. Confira o método na página do endpoint.

Outros códigos de erro (402 / 404 / 409 / 422 / 500)

Código	HTTP	Nome	Repetir	Descrição
402402	402	`VALIDATION_ERROR`	não	Herdado do catálogo anterior. Não foi reproduzido, e o único exemplo que o mostrava veio copiado de outro endpoint. A semântica real precisa de confirmação — use `400400` como código de validação.
404404	404	`NO_SUCH_ENTITY`	não	Consta neste catálogo. Na prática, um objeto ausente devolve `400404`.
409293	409	—	mais tarde	Conflito de estado em uma transcrição do Speak. Conhecido apenas pelo exemplo de resposta do Speak; não reproduzido.
422100	422	—	sim	Uma transcrição do Speak ainda não está pronta. Conhecido apenas pelo exemplo de resposta do Speak; não reproduzido.
500500	500	`INTERNAL_SERVER_ERROR`	sim	Erro interno do servidor. Reproduzido em `GET /v1/videos?page=0`. Repita com backoff exponencial; se os mesmos parâmetros falharem sempre, repetir não vai ajudar.

Tratamento de erros

Novas tentativas. É seguro repetir respostas 5xx e tempos de espera de rede com backoff exponencial; limite a cinco tentativas. As demais respostas 4xx não devem ser repetidas — corrija a requisição antes.
Limites de requisições. O API não envia RateLimit-* nem Retry-After. O guia para desenvolvedores indica 10 requisições por segundo e 300 por minuto, mas 50 requisições paralelas passaram sem nenhum 429, então trate o número publicado como não confirmado e aguarde pelo menos 5 segundos antes de repetir após um deles.
Validação. Interprete error.invalid_params — name é o campo a corrigir e message lista os valores aceitos. Quando invalid_params não vem, o nome do parâmetro está dentro de message.
Identificadores. 400301 e 400302 significam que o identificador não pôde ser interpretado, não que o objeto esteja ausente. Objeto ausente é 400404.
Repetir um POST. Idempotency-Key não é suportado de nenhuma forma documentada. Parta do princípio de que repetir um POST após um tempo esgotado cria um segundo objeto; consulte a lista antes de repetir.
Logs. Registre error.code e X-Request-ID, não error.message: os códigos são estáveis, as mensagens não.

Os códigos e formatos desta página foram verificados contra o API de produção em 24-09-2026. As linhas marcadas como não reproduzidas vêm do catálogo anterior ou de exemplos de resposta e ainda precisam de confirmação.