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 ResponseMeaningAction to Take
400The request has not been applied because it lacks valid authentication credentialsCheck that you have set the correct API Key. Contact us if the problem persists.
401/403The current hit should be blocked according to rulesThe module should stop processing the hit and output the HTML code returned by the API in the body section.
301/302The current hit should be redirected to a specific pageThe module should redirect to the “Location” field found in API Response header.
200The hit should be allowedThe 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
UnlimitedKey, IP, Port, Protocol, Method, CookiesLen, AuthorizationLen, ModuleVersion, PostParamLen, APIConnectionState, RequestModuleName, TimeRequest
128ClientID, X-Requested-With, AcceptCharset, AcceptEncoding, Connection, Pragma, CacheControl
256AcceptLanguage
512HeadersList, Origin, ServerHostname, ServerName, XForwardedForIP, Accept, Host
768UserAgent
1024Referer
2048Request
Language
Click Try It! to start a request and see the response here!