# Erros e Paginação Esta página aborda duas coisas que toda integração precisa lidar: como é uma solicitação com falha e como paginar endpoints que retornam listas. --- ## O envelope de erro Quando uma solicitação falha, a resposta é sempre um JSON com o mesmo formato — um sinalizador `success` definido como `false`, uma mensagem `error` legível por humanos e um `error_code` numérico que corresponde ao status HTTP: ```json { "success": false, "error": "Invalid cursor", "error_code": 400 } ``` Como `success` e `error_code` estão sempre presentes, você pode criar ramificações com base neles sem precisar inspecionar códigos de status HTTP brutos, se preferir. Uma resposta bem-sucedida sempre tem `success: true`. --- ## Códigos de status | Status | `error_code` | Meaning | What to do | |---|---|---|---| | `200` | — | Success | Read the response data. | | `201` | — | Resource created | Save the returned ID (e.g. `campaign_id`, `contactId`). | | `400` | `400` | Bad request | A parameter is missing or invalid. Read the `error` message and fix the request. | | `401` | `401` | Unauthorized | Your API key is missing or invalid. Check the key and how you are sending it — see [Authentication](authentication.md). | | `403` | `403` | Forbidden | Your plan does not include API access. See [API Access](../integrations/api-access.md) or contact [hi@youraiconnector.com](mailto:hi@youraiconnector.com). | | `404` | `404` | Not found | The resource (e.g. a contact, campaign, or task ID) does not exist on your account. | | `409` | `409` | Conflict | The resource already exists — for example, creating a contact whose phone number is already on your account. | | `429` | `429` | Rate limited | You have exceeded 300 requests per minute (or the wider 1,200/minute account ceiling). Back off and retry shortly. | | `500` | `500` | Server error | Something went wrong on our side. Retry after a short wait; email [hi@youraiconnector.com](mailto:hi@youraiconnector.com) if it persists. | Alguns exemplos de como isso se parece na prática: ```json { "success": false, "error_code": 401, "error": "Invalid API key" } ``` ```json { "success": false, "error": "A contact with this phone number already exists", "error_code": 409 } ``` ```json { "success": false, "error_code": 429, "error": "Rate limit exceeded. Please try again later." } ``` ### Lidando bem com erros - **Verifique `success` (ou o código de status) antes de ler os dados.** Não presuma que o corpo da resposta tenha o campo que você espera. - **Tente novamente `429` e `500` com um curto intervalo** — aguarde e tente novamente. Não tente novamente `400`, `401`, `403`, `404` ou `409`; eles continuarão falhando até que você altere a solicitação. - **Leia a mensagem `error`.** Ela geralmente informa exatamente qual campo está incorreto. --- ## Paginação Endpoints de lista (como `GET /contacts`, `GET /campaigns` e `GET /tasks`) retornam resultados em páginas para que uma única chamada nunca precise carregar toda a sua conta. A paginação usa um cursor opaco. Dois parâmetros de consulta controlam isso: | Parâmetro | Descrição | |---|---| | `limit` | Quantos itens retornar por página. Os padrões variam de acordo com o endpoint (geralmente 50); o máximo é **100**. | | `cursor` | Um ponteiro opaco para a próxima página. Deixe-o de fora na primeira página. | Cada página inclui um campo `next_cursor` na resposta: - Se `next_cursor` for uma string, há mais resultados — passe-a como `cursor` na sua próxima solicitação. - Se `next_cursor` for `null`, você chegou à última página. Pare. Uma única página de contatos tem esta aparência: ```json { "success": true, "contacts": [ { "id": "abc123", "first_name": "Jane", "phone_number": "+15551234567" }, { "id": "def456", "first_name": "John", "phone_number": "+15557654321" } ], "next_cursor": "eyJsYXN0IjoiZGVmNDU2In0" } ``` ::: note **Nota:** Um cursor é opaco — não tente analisar, construir ou modificá-lo. Apenas passe de volta um valor `next_cursor` que você recebeu de uma resposta anterior. ::: --- ## Paginação de todos os contatos Para coletar uma lista inteira, comece sem um cursor e continue chamando até que `next_cursor` retorne `null`. **cURL** Este exemplo percorre as duas primeiras páginas manualmente. Execute a primeira chamada, copie o `next_cursor` da resposta para `CURSOR` e, em seguida, execute a segunda chamada. Repita até que `next_cursor` seja `null`. ```bash # First page curl "https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY&limit=100" # Next page — paste the next_cursor from the previous response CURSOR="eyJsYXN0IjoiZGVmNDU2In0" curl "https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY&limit=100&cursor=$CURSOR" ``` **JavaScript** ```javascript async function getAllContacts() { const all = []; let cursor = null; do { const url = new URL("https://api.youraiconnector.com/v1/contacts"); url.searchParams.set("limit", "100"); if (cursor) url.searchParams.set("cursor", cursor); const res = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); if (!data.success) throw new Error(data.error); all.push(...data.contacts); cursor = data.next_cursor; } while (cursor); return all; } ``` **Python** ```python import requests def get_all_contacts(): all_contacts = [] cursor = None while True: params = {"limit": 100} if cursor: params["cursor"] = cursor res = requests.get( "https://api.youraiconnector.com/v1/contacts", params=params, headers={"X-API-Key": "YOUR_API_KEY"}, ) data = res.json() if not data["success"]: raise Exception(data["error"]) all_contacts.extend(data["contacts"]) cursor = data["next_cursor"] if not cursor: break return all_contacts ``` O mesmo loop funciona para qualquer endpoint paginado — basta alterar o caminho e o campo que você lê da resposta (`campaigns`, `tasks`, e assim por diante). --- ## Próximos passos - [Autenticação](authentication.md) — as quatro maneiras de enviar sua chave. - [Contatos](contacts.md) — os endpoints completos de contatos usados nos exemplos acima. - [Chaves de API](api-keys.md) — verifique o uso do seu limite de taxa em tempo real para evitar `429`s.