Responses

When you interact with the Adlocaite API, you receive immediate responses with the results of your requests. This guide explains how to handle these API responses effectively.

API responses

All API endpoints return JSON responses with a consistent structure. Here are the main response types you'll encounter:

Successful responses

When your API request is successful, you'll receive a response with relevant data:

{
  "success": true,
  "offer_id": "offer_1733242800_abc12345",
  "bid_price_cents": 1500,
  "asset_url": "https://cdn.example.com/assets/ad_image_1920x1080.jpg",
  "ots": 1200,
  "expires_at": "2025-08-04T12:40:45.123Z"
}

Error responses

When something goes wrong, you'll receive an error response:

{
  "error": "SCREEN_NOT_FOUND",
  "message": "Screen not found or access denied"
}

Response handling

When you interact with the API, responses are returned immediately with the result of your request.

Offer request responses

When requesting an offer, you receive immediate feedback:

Success response:

{
  "offer_id": "offer_1733242800_abc12345",
  "bid_price_cents": 1500,
  "asset_url": "https://cdn.example.com/assets/ad_image_1920x1080.jpg",
  "ots": 1200,
  "expires_at": "2025-08-04T12:40:45.123Z"
}

Error response:

{
  "error": "NO_MATCHES",
  "message": "No suitable advertisements found for this screen"
}

Offer acceptance responses

When accepting an offer, you get confirmation or error details:

Acceptance confirmed:

{
  "success": true,
  "message": "Offer accepted successfully",
  "deal_id": "deal_1733242800_def67890"
}

Acceptance failed:

{
  "error": "OFFER_EXPIRED",
  "message": "This offer has expired and cannot be accepted"
}

Error handling

The API uses standard HTTP status codes and returns structured error messages:

Common error codes

Error response format

All errors follow this structure:

{
  "error": "ERROR_CODE",
  "message": "Human-readable error description"
}

Best practices

• Check status codes - Always verify the HTTP status code first
• Handle timeouts - Implement reasonable timeout values for requests
• Retry logic - Implement exponential backoff for temporary failures
• Log errors - Keep detailed logs for troubleshooting
• Validate responses - Check for required fields before processing