> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shappire.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Problemas comuns na integração com a Shappire Media API

## 401 invalid\_api\_key

* Confirme o header `X-API-Key` (sem typo no prefixo `shp_live_`)
* Verifique se a chave não foi revogada no dashboard
* Não use aspas extras no valor do header

## 403 forbidden

* Chave sem escopo `media:resolve` ou `media:download` na rota
* Projeto desativado ou inexistente

## 422 unsupported\_platform

* Host não suportado — consulte `GET /platforms`
* URL encurtada: expanda para URL canônica quando possível

## 404 media\_not\_found

* `media_id` expirou após o resolve — execute resolve novamente
* `media_id` de outro projeto

## Job preso em queued

* Worker pode estar ocupado — aguarde até 60 s
* Verifique limite de concorrência (2 jobs simultâneos)
* Persiste? Abra suporte com `request_id` do header

## download\_url retorna 403

* URL assinada expirou — consulte o job novamente ou reenfileire
* Não modifique query params da URL assinada

## Rate limit 429

* Respeite `X-RateLimit-Reset`
* Reduza frequência de polling em jobs
* Veja [Rate limiting](/api-reference/rate-limiting)

## Desenvolvimento local

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
# API local
curl http://localhost:8080/v1/health

# Com chave
curl http://localhost:8080/v1/platforms \
  -H "X-API-Key: shp_test_ou_live_sua_chave"
```

Certifique-se de que `MONGO_URL` e workers estão rodando no `apps/api`.