Limites
Os limites de tamanho, de quantidade e de requisições por segundo da API.
Todos os limites da API em um só lugar. Os valores das outras páginas da documentação vêm desta mesma lista.
| Limite | Valor |
|---|---|
| Tamanho do PDF, por URL ou upload em duas etapas | 10 MB |
| Tamanho do PDF, em multipart/form-data | 4 MB |
| Tamanho do PDF, em base64 (depois de decodificado) | 3 MB |
| Corpo da requisição | 4,5 MB |
| Validade do upload_url de um upload | 2 horas |
| Prazo para usar um upload numa correspondência | 24 horas |
| Folhas por correspondência, contando a que o endereço às vezes acrescenta | 6 folhas |
| Espera pelo download de document.url | 10 segundos |
| Variáveis do PDF por correspondência | 100 variáveis |
| Nome de uma variável do PDF | 60 caracteres |
| Valor de uma variável do PDF, numa linha | 500 caracteres |
| Chaves em metadata | 20 chaves |
| Nome de uma chave de metadata | 40 caracteres |
| Valor de uma chave de metadata | 500 caracteres |
| reference | 100 caracteres |
| Idempotency-Key | 255 caracteres |
| Validade de uma Idempotency-Key | 24 horas |
| Requisições por segundo, por conta | 50 por segundo |
| Itens por página nas listagens | 100 itens |
| Eventos guardados | 30 dias |
| PDF disponível em preview_url, no mínimo | 90 dias |
| Agendamento com send_date, no máximo | 180 dias à frente |
| Códigos errados por verificação | 5 tentativas |
| Prazo para confirmar o código, após a postagem | 60 dias |
| Prazo para compartilhar a localização na página, após a confirmação | 30 minutos |
| Prazo para o seu webhook responder | 15 segundos |
Requisições por segundo
Cada conta pode fazer até 50 requisições por segundo. O limite vale para a conta inteira, somando todas as chaves.
Toda resposta traz cabeçalhos com a situação do limite:
| Cabeçalho | O que é |
|---|---|
RateLimit-Limit | Quantas requisições por segundo a conta pode fazer. |
RateLimit-Remaining | Quantas ainda cabem no segundo atual. |
RateLimit-Reset | Em quantos segundos a contagem recomeça. |
Quando a conta passa do limite, a API responde 429 com rate_limit_exceeded e o cabeçalho Retry-After, com os segundos a esperar. Nada é criado. Espere esse tempo e repita com a mesma Idempotency-Key.
HTTP/1.1 429 Too Many Requests
Retry-After: 1
RateLimit-Limit: 50
RateLimit-Remaining: 0
RateLimit-Reset: 1Tamanho dos arquivos
O corpo de uma requisição tem até 4,5 MB. Por isso um PDF enviado dentro da requisição tem até 4 MB em multipart/form-data e até 3 MB em base64. Por URL ou pelo upload em duas etapas (POST /v1/uploads), o PDF pode ter até 10 MB. Veja Documento e área do endereço.
Envios grandes
Para enviar milhares de correspondências, como as faturas do mês:
- Confira o custo antes. Simule uma correspondência típica com
POST /v1/letters/quotee compare o total com o saldo emGET /v1/balance. Uma correspondência enviada na hora só é criada quando o saldo cobre o preço. - Use uma fila com poucos processos em paralelo. Coloque cada correspondência em uma fila e consuma com alguns processos, de 5 a 10. Isso fica bem abaixo do limite e deixa espaço para as outras chamadas do seu sistema.
- Dê uma
Idempotency-Keypara cada correspondência, como o id da fatura. Se uma parte do envio falhar e você rodar de novo, as que já foram criadas não se repetem. Veja Idempotência. - Trate o 429 como sinal para ir mais devagar. Respeite o
Retry-Afterantes de continuar. - Acompanhe o resultado por webhooks, não consultando cada correspondência. Veja Webhooks.
Se você já sabe a data de um envio grande, agende com send_date: as correspondências ficam validadas e prontas, e o saldo só precisa cobrir o total na data do envio.
Precisa de mais
Se o seu volume precisa de um limite maior, fale com a CartaFlow pelo painel.