Erros

Toda resposta da API REST do VDClip sob https://api.vdclip.com/v1 usa o mesmo resposta JSON direta, seja a requisição bem-sucedida ou com falha, então seu tratamento de erros é escrito uma vez e reutilizado em todo lugar. Ramifique pelo error.code para a lógica, e mostre error.message a um desenvolvedor.

Somente servidor-a-servidor

A API REST não tem suporte a CORS. As chamadas devem ser feitas a partir do seu backend com o cabeçalho Authorization: Bearer vdck_.... Nunca embuta uma chave de API em um navegador, app móvel ou qualquer cliente que chegue aos usuários finais. Uma requisição de uma origem rejeitada retorna ORIGIN_REJECTED.

Formato de erro

Endpoints /v1/* com falha retornam este formato de nível superior:


{
  "errors": [
    {
      "code": "INSUFFICIENT_CREDITS",
      "description": "Not enough credits to start this render."
    }
  ]
}

Campo	Tipo	Notas
`errors`	array	Um ou mais itens de erro.
`errors[].code`	string	Um identificador estável em maiúsculas. Ramifique sua lógica por ele.
`errors[].description`	string	Um diagnóstico curto, em inglês, para desenvolvedores. Não faça parse dele.
`X-Request-ID`	string	Um id único para esta requisição. Sempre registre.

Em caso de sucesso, endpoints retornam o recurso diretamente. Campos de paginação e limites ficam definidos por endpoint na spec OpenAPI.

Sempre registre o X-Request-ID

Toda resposta carrega um X-Request-ID. Registre-o tanto para sucessos quanto para falhas. Ao contatar o suporte em contact@vdclip.com, inclua o X-Request-ID da chamada com falha para que possamos rastrear a requisição exata em nossos logs. Sem ele, a depuração é muito mais lenta.

Códigos de erro

Todos os códigos de erro, o status HTTP e o que significam. O status HTTP e o error.code sempre concordam, então você pode ramificar por qualquer um.

`error.code`	HTTP	Significado
`INVALID_API_KEY`	401	O cabeçalho `Authorization` está ausente, malformado, revogado ou desconhecido.
`MISSING_SCOPE`	403	A chave é válida, mas não tem o escopo que este endpoint exige.
`INSUFFICIENT_CREDITS`	402	A conta não tem créditos suficientes para esta ação.
`RATE_LIMITED`	429	Requisições demais. Respeite o cabeçalho `Retry-After` antes de repetir.
`VALIDATION_ERROR`	422	O corpo da requisição ou os parâmetros de query falharam na validação.
`INVALID_JSON`	400	O corpo da requisição não é JSON válido e não pôde ser parseado.
`NOT_FOUND`	404	O recurso não existe ou não pertence a esta conta.
`ORIGIN_REJECTED`	403	A requisição veio de um navegador ou origem não permitida. Chame a partir do seu servidor.
`UPSTREAM_ERROR`	502	Uma dependência falhou. Transitório. Repita com backoff exponencial.

Novos códigos podem ser adicionados em versões minor. Trate um error.code não reconhecido como uma falha genérica e recorra a success e ao status HTTP. Códigos existentes nunca são reaproveitados.

O que cada erro significa

🔑

INVALID_API_KEY

401. A chave está ausente, malformada, revogada ou não reconhecida. Confirme que você está enviando Authorization: Bearer vdck_... e que a chave ainda está ativa.

🚫

MISSING_SCOPE

403. A chave funciona, mas não carrega o escopo que este endpoint precisa. Os escopos usam o formato vdclip:resource:action. Reemita a chave com o escopo necessário.

💳

INSUFFICIENT_CREDITS

402. A ação precisa de mais créditos do que a conta tem. Recarregue ou faça upgrade. Veja a página de preços para o que cada plano inclui.

⏳

RATE_LIMITED

429. Você enviou requisições rápido demais. A resposta inclui um cabeçalho Retry-After em segundos. Aguarde esse tempo e depois repita.

📝

VALIDATION_ERROR

422. Um campo no corpo ou na query string está ausente ou inválido. A mensagem nomeia o que falhou. Corrija a requisição e reenvie.

📦

INVALID_JSON

400. O corpo da requisição não é JSON parseável. Verifique sua serialização e o cabeçalho Content-Type, e depois reenvie.

🔍

NOT_FOUND

404. O id do recurso não existe, ou pertence a outra conta. Verifique o id e se sua chave é dona do recurso.

🌐

ORIGIN_REJECTED

403. A chamada veio de um navegador ou de uma origem que a API não permite. A API é somente servidor-a-servidor, sem CORS. Mova a chamada para o seu backend.

🔧

UPSTREAM_ERROR

502. Uma dependência interna falhou. Isso geralmente é transitório. Repita com backoff exponencial e registre o request_id se persistir.

Escopos restritos por plano

Dois escopos são restritos por plano: vdclip:render:execute e vdclip:social:publish. Se sua chave tem um desses escopos, mas seu plano não inclui o recurso, a chamada retorna MISSING_SCOPE ou INSUFFICIENT_CREDITS dependendo da restrição. Revise o que seu plano cobre na página de preços antes de depender desses endpoints. Para a lista completa de escopos e quais endpoints os exigem, veja Autenticação.

Lidando com limites de taxa

Quando você recebe RATE_LIMITED (HTTP 429), a resposta carrega um cabeçalho Retry-After que diz quantos segundos esperar antes de tentar de novo:


HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json
 
{
  "errors": [
    {
      "code": "RATE_LIMITED",
      "description": "Rate limit exceeded. Retry after 12 seconds."
    }
  ]
}

Respeite o Retry-After em vez de repetir imediatamente. Para mais detalhes sobre limites e estratégia de backoff, veja Limites de taxa.

OAuth e clientes de agente

O envelope aqui se aplica aos endpoints /v1/* autenticados com Authorization Bearer. O Servidor de Autorização OAuth 2.1 em /oauth2/* e /.well-known/* (emissor https://api.vdclip.com), usado por servidores MCP, agentes de IA e integrações de terceiros com Authorization: Bearer <JWT>, retorna corpos RFC padrão. Trate seus erros separadamente. Veja OAuth.

Dicas e Boas Práticas

Ramifique pelo error.code

Use o código estável em maiúsculas para a lógica. Nunca faça parse de error.message, que é uma string livre em inglês destinada a desenvolvedores.

Registre todo request_id

Armazene X-Request-ID tanto em sucesso quanto em falha. É a forma mais rápida de o suporte rastrear uma chamada.

Respeite o Retry-After

Em um 429 RATE_LIMITED, leia o cabeçalho Retry-After e aguarde o número de segundos indicado antes de repetir.

Repita apenas erros transitórios

Repita UPSTREAM_ERROR (502) e RATE_LIMITED (429) com backoff. Não repita erros de validação, escopo ou crédito. Corrija a requisição ou a conta.

Mantenha as chaves no servidor

A API não tem CORS. Chamar a partir de um navegador gera ORIGIN_REJECTED e corre o risco de vazar sua chave. Sempre chame a partir do seu backend.