# Erros e Paginação Esta página aborda dois aspetos que todas as integrações precisam de gerir: como é um pedido falhado e como paginar através de endpoints que devolvem listas. --- ## O envelope de erro Quando um pedido falha, a resposta é sempre JSON com a mesma estrutura — um sinalizador `success` definido como `false`, uma mensagem `error` legível por humanos e um `error_code` numérico que corresponde ao estado HTTP: ```json { "success": false, "error": "Invalid cursor", "error_code": 400 } ``` Como `success` e `error_code` estão sempre presentes, pode ramificar com base neles sem inspecionar códigos de estado HTTP brutos, se preferir. Uma resposta bem-sucedida tem sempre `success: true`. --- ## Códigos de estado | 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 isto se apresenta 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." } ``` ### Gerir erros corretamente - **Verifique `success` (ou o código de estado) antes de ler os dados.** Não assuma que o corpo da resposta contém o campo que espera. - **Tente novamente `429` e `500` com um curto período de espera** — aguarde e tente de novo. Não tente novamente `400`, `401`, `403`, `404` ou `409`; estes continuarão a falhar até que altere o pedido. - **Leia a mensagem `error`.** Geralmente, indica exatamente qual é o campo incorreto. --- ## Paginação Os endpoints de lista (como `GET /contacts`, `GET /campaigns` e `GET /tasks`) devolvem resultados em páginas para que uma única chamada nunca tenha de carregar toda a sua conta. A paginação utiliza um cursor opaco. Dois parâmetros de consulta controlam-na: | Parâmetro | Descrição | |---|---| | `limit` | Quantos itens devolver por página. Os valores predefinidos variam consoante o endpoint (frequentemente 50); o máximo é **100**. | | `cursor` | Um ponteiro opaco para a página seguinte. Deixe-o vazio para a primeira página. | Cada página inclui um campo `next_cursor` na resposta: - Se `next_cursor` for uma string, existem mais resultados — passe-a como o `cursor` no seu próximo pedido. - Se `next_cursor` for `null`, chegou à última página. Pare. Uma única página de contactos tem o seguinte aspeto: ```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 modificar o mesmo. Apenas devolva um valor `next_cursor` que tenha recebido de uma resposta anterior. ::: --- ## Paginação de todos os contactos Para recolher uma lista completa, comece sem cursor e continue a chamar até que `next_cursor` devolva `null`. **cURL** Este exemplo percorre manualmente as duas primeiras páginas. Execute a primeira chamada, copie o `next_cursor` da sua 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 ciclo funciona para qualquer endpoint paginado — basta alterar o caminho e o campo que lê da resposta (`campaigns`, `tasks`, e assim sucessivamente). --- ## Próximos passos - [Autenticação](authentication.md) — as quatro formas de enviar a sua chave. - [Contactos](contacts.md) — os endpoints de contacto completos utilizados nos exemplos acima. - [Chaves de API](api-keys.md) — verifique a sua utilização de limite de taxa em tempo real para evitar `429`s.