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 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

• 418 — Deprecated API version. See Deprecated Endpoints

• 429 Too Many Requests — You are being rate-limited or have triggered a login ban. Includes a Retry-After header. See Banning and 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.

This is the most common integration mistake. Make sure your HTTP client is sending form-encoded parameters, not a JSON body.

Banning

The API enforces automatic banning to protect against brute-force login attempts.

How it works

1

After several failed login attempts, the triggering request returns 429 Too Many Requests with a Retry-After header

2

All subsequent requests while the ban is active return 401 Unauthorized — the ban is invisible from the response alone

3

Ban duration escalates with each additional failed attempt, up to a maximum of 24 hours

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 [email protected]

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 [email protected].