Handle API Response

API calls return HTTP codes and Headers that you can use inside your module or application.

API Response Code

Module behavior must change depending of the following API response code:

API Response

Meaning

Action to Take

400

The request has not been applied because it lacks valid authentication credentials

Check that you have set the correct API Key. Contact us if the problem persists.

401/403

The current hit should be blocked according to rules

The module should stop processing the hit and output the HTML code returned by the API in the body section.

301/302

The current hit should be redirected to a specific page

The module should redirect to the “Location” field found in API Response header.

200

The hit should be allowed

The module should let the application proceed.

Any other response code should be ignored.

The module must check if the HTTP response code has the same value as the X-DataDomeResponse header. If not, the module must act like it is a 200 code.

Each DataDome request should also have X-DataDome header with value protected that can be sent in different cases, for example as Protected.

All these headers are sent via server-side integration like http, http_raw, spoa etc.

When APIServer blocks a request and the response has content-type application/json that is forced by segment or accept-headers, it also adds X-DD-B headers to both client-side and server-side integrations.

API Response Header

The module must parse the headers:

  • “X-DataDome-request-headers”, which contain the name of the headers that must be added to the request.
  • “X-DataDome-headers”, which contain the name of the headers that must be added to the final client response.

API Server response headers example:

X-DataDome-request-headers: X-DataDome-botname X-DataDome-botfamily X-DataDome-isbot
X-DataDome-botname: Crawler fake Google
X-DataDome-botfamily: bad_bot
X-DataDome-isbot: 1
X-DataDome-headers: Set-Cookie Pragma X-DataDome Cache-Control
Set-Cookie: datadome=some-value; Domain=domain.com; Path=/; Expires=Wed, 13 Jan 2021 22:23:01 GMT;
Pragma: no-cache
X-DataDome: protected
Cache-Control: no-cache
X-DataDomeResponse: 403

Module should add the below to client request:

X-DataDome-botname: Crawler fake Google
X-DataDome-botfamily: bad_bot
X-DataDome-isbot: 1

Module should add to the below to client response:

Set-Cookie: datadome=some-value; Domain=domain.com; Path=/; Expires=Wed, 13 Jan 2021 22:23:01 GMT;
Pragma: no-cache
X-DataDome: protected
Cache-Control: no-cache

API Field Size

API servers won't accept incoming body requests that are larger than 24kb.
Each field must be truncated by the module according to the below rules:

Limit (in bytes)

Fields

Unlimited

Key, IP, Port, Protocol, Method, CookiesLen, AuthorizationLen, ModuleVersion, PostParamLen, APIConnectionState, RequestModuleName, TimeRequest

128

ClientID, X-Requested-With, AcceptCharset, AcceptEncoding, Connection, Pragma, Cache-Control

256

AcceptLanguage

512

HeadersList, Origin, ServerHostname, ServerName, XForwardedForIP, Accept, Host

768

UserAgent

1024

Referer

2048

Request

Language
Response
Click Try It! to start a request and see the response here!