> For the complete documentation index, see [llms.txt](https://dev.realpadsoftware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dev.realpadsoftware.com/integrations/readme/authentication-and-error-handling.md). # Authentication and Error Handling This page is a reference for authentication, HTTP status codes, and error handling across all Realpad API endpoints. If you're new to the API, start with the [Getting Started](/integrations/readme/quickstart-guide.md) guide. ## Authentication Every API request requires two form parameters: * `login` — your integration account username * `password` — your integration account password Credentials are sent as part of the request body (form-encoded), not as HTTP headers. ### Credential scoping * Credentials are typically scoped to **specific projects** and **specific API areas** (e.g., Landing Page, Data Takeout, Payments) * The convention for the project landing integrations is to have **two credential pairs per project**: one for pricelist endpoints, one for lead submission * A single set of credentials cannot access endpoints outside its assigned area ### Invitation acceptance Your credentials are delivered via an invitation email. You must **accept the invitation** before credentials become active. If you attempt to authenticate before accepting, you will receive a 401 response. ## HTTP Status Codes All endpoints use the following status codes consistently: * **200 OK** — Request succeeded * **201 Created** — A new resource was created (e.g., a new lead via `create-lead`) * **400 Bad Request** — Missing, invalid, or unexpected parameters. The response body contains a specific error message * **401 Unauthorized** — Invalid credentials, insufficient permissions, or your account is currently banned * **403 Forbidden** — Your account requires consent acceptance. Log into the Realpad web interface to provide consent * **415 Unsupported Media Type** — Wrong Content-Type header. See [Content-Type Requirements](#content-type-requirements) * **418** — Deprecated API version. See [Deprecated Endpoints](#deprecated-endpoints) * **429 Too Many Requests** — You are being rate-limited or have triggered a login ban. Includes a `Retry-After` header. See [Banning](#banning) and [Rate Limiting](#rate-limiting) * **500 Internal Server Error** — Unexpected server error. If this persists, contact support ### How to handle errors * **4xx errors** mean the request is wrong — stop and fix the problem (bad credentials, wrong Content-Type, missing parameters) before retrying. Repeating the same request will produce the same error. * **5xx errors** mean something went wrong on our side — wait a moment and retry. If it keeps failing, increase the wait time between retries (e.g., 1 second, then 5, then 30). If the problem persists, contact support. ## Content-Type Requirements All POST requests must use one of: * `application/x-www-form-urlencoded` * `multipart/form-data` Sending any other Content-Type (most commonly `application/json`) results in a **415** response: ``` Unsupported Content-Type: application/json. This endpoint expects application/x-www-form-urlencoded or multipart/form-data. ``` If the Content-Type is correct but the body is actually JSON, the API detects this and returns a **400** response: ``` Incorrect parameter format. The request body appears to be JSON, but this endpoint expects application/x-www-form-urlencoded parameters. ``` {% hint style="warning" %} This is the most common integration mistake. Make sure your HTTP client is sending form-encoded parameters, not a JSON body. {% endhint %} ## Banning The API enforces automatic banning to protect against brute-force login attempts. ### How it works {% stepper %} {% step %} After several failed login attempts, the triggering request returns **429 Too Many Requests** with a [`Retry-After`](#retry-after-header) header {% endstep %} {% step %} All subsequent requests while the ban is active return **401 Unauthorized** — the ban is invisible from the response alone {% endstep %} {% step %} Ban duration **escalates** with each additional failed attempt, up to a maximum of 24 hours {% endstep %} {% endstepper %} ### How to avoid bans * **Never** rotate or retry credentials in a loop — if a request returns 401, stop and investigate * Store credentials securely and avoid typos in automated systems * If testing in development, use a dedicated test account ### How to recover * Wait for the duration indicated by the `Retry-After` header on the 429 response that triggered the ban * There is no manual reset available via the API * If you are locked out and need immediate assistance, contact ## Retry-After Header The `Retry-After` header is present on all **429** responses. Its value is an **integer representing seconds** until you can retry. ``` HTTP/1.1 429 Too Many Requests Retry-After: 120 ``` This header appears in two scenarios: * **Login ban triggered** — indicates how long the ban lasts * **Rate limit hit** — indicates when you can call the endpoint again Always read and respect this header in your integration code. ## Rate Limiting Some endpoints enforce a cooldown period between consecutive calls. This applies primarily to **Data Takeout** endpoints (`list-excel-*`), which are expensive to compute. * Rate limits are enforced **per user, per endpoint** * Calling a rate-limited endpoint too frequently returns **429 Too Many Requests** with a `Retry-After` header * The cooldown resets after each successful call If you need to export data from multiple endpoints, you can call different endpoints concurrently — the cooldown only applies to repeated calls to the **same** endpoint. ## Deprecated Endpoints Requests to deprecated API versions return **418** with the message: ``` This API version is deprecated. ``` All current endpoints use API version **v10** (URL pattern: `/ws/v10/{endpoint-name}`). Earlier versions (v01–v09) are deprecated and no longer functional. Need help? Contact . --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://dev.realpadsoftware.com/integrations/readme/authentication-and-error-handling.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.