Standard Responses and Errors

Overview

The PulsePoint DSP API uses consistent response formats and error codes across all endpoints to provide predictable, actionable feedback for API integrations.Response StructureSuccessful ResponsesAll successful API responses return HTTP status codes in the 2xx range with a JSON payload containing the requested resource data.

❗️

Standard errors and responses were implemented in v2+ of the APIs. If you are still on v1, this page will not be consistent with what you see in your responses.

Example Successful Response From GET Campaign:

{
  "success": true,
  "requestId": 9384018-1038-0-3138490,
  "data": {
    "campaignId": 22605,
    "name": "adchoices icon Test",
    "budgetCap": 10
  }
}

Request ID Usage The requestId field is a unique identifier generated for each API request. Include this ID when:

1. Reporting issues to support
2. Debugging production problems
3. Correlating errors across systems

Error Responses

All error responses follow a standardized structure with consistent HTTP status codes, machine-readable error codes, and detailed context for debugging.

Standard Error Format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": [
      {
        "field": "path.to.field",
        "message": "Specific issue description",
        "code": "FIELD_LEVEL_ERROR_CODE",
        "value": "actual_value_provided",
        "expected": "description_of_expected_value"
      }
    ]
  },
  "timestamp": "2025-10-08T14:30:00.000Z",
  "path": "/api/v2/endpoint",
  "request_id": "req_abc123"
}

Standard Error Format Fields

Detail Object Fields

HTTP Status Codes

HTTP status codes are returned in the response status line (e.g., HTTP/1.1 400 Bad Request) and are not repeated in the response body. Use the HTTP status code for top-level error classification, and use the error.code field in the JSON body for specific, programmatic error handling.

📘

Note: The HTTP status code is accessible via your HTTP client (e.g., response.status in JavaScript, response.status_code in Python). It is not duplicated in the JSON body.

Standard Error Codes

Validation Errors (HTTP 400)

Business Logic Errors (HTTP 422)

Not Found Errors (HTTP 404)

Authorization Errors (HTTP 403)

Rate Limiting Errors (HTTP 429)

Server Errors (HTTP 500)

Error Response Examples

• Validation Error - Missing Required Fields
• Request: POST /api/v1/lineItems
• Response: HTTP 400

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Line item validation failed",
    "details": [
      {
        "field": "name",
        "message": "Line item name is required",
        "code": "REQUIRED_FIELD"
      },
      {
        "field": "costModel",
        "message": "Cost model is required",
        "code": "REQUIRED_FIELD",
        "expected": "One of: CPM, FIXED CPM"
      }
    ]
  },
  "timestamp": "2025-10-08T22:32:02.000Z",
  "path": "/api/v1/lineItems",
  "request_id": "req_xyz789"
}

• Validation Error - Invalid Format
• Request: POST /api/v1/lineItems
• Response: HTTP 400

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "flights[0].startDate",
        "message": "Date must be in format YYYY-MM-DD HH:MM",
        "code": "INVALID_FORMAT",
        "value": "2025/10/08 2:30pm",
        "expected": "YYYY-MM-DD HH:MM (e.g., 2025-10-08 14:30)"
      }
    ]
  },
  "timestamp": "2025-10-08T14:30:00.000Z",
  "path": "/api/v1/lineItems",
  "request_id": "req_ghi789"
}

• Validation Error - Invalid Enum Value
• Request: POST /api/v1/lineItems
• Response: HTTP 400

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "costModel",
        "message": "Invalid cost model",
        "code": "INVALID_ENUM",
        "value": "CPV",
        "expected": "One of: CPM, fixedCPM"
      }
    ]
  },
  "timestamp": "2025-10-08T14:30:00.000Z",
  "path": "/api/v1/lineItems",
  "request_id": "req_jkl012"
}

• Business Logic Error - Budget Exceeded
• Request: POST /api/v1/lineItems
• Response: HTTP 422

{
  "success": false,
  "error": {
    "code": "BUSINESS_RULE_VIOLATION",
    "message": "Campaign operation violates business rules",
    "details": [
      {
        "field": "flights",
        "message": "Total flight budget exceeds campaign budget",
        "code": "BUDGET_EXCEEDED",
        "value": {
          "totalFlightBudget": 15000.00,
          "campaignBudget": 10000.00
        },
        "expected": "Total flight budget must not exceed campaign budget cap"
      }
    ]
  },
  "timestamp": "2025-10-08T14:30:00.000Z",
  "path": "/api/v1/lineItems",
  "request_id": "req_bcd890"
}

Best Practices for Error Handling

For API Consumers

1. Check HTTP Status Codes First: Use status codes to determine the category of error before parsing the response body.
2. Use Error Codes for Logic: The error.code field is stable and should be used for programmatic error handling rather than parsing error messages.
3. Display Error Messages: The error.message and details[].message fields are human-readable and can be displayed to end users.
4. Include Request IDs in Support Emails: Always include the request_id when contacting support about API issues.
5. Handle Multiple Validation Errors: The details array may contain multiple validation errors. Display all of them to help users correct their requests in one iteration.
6. Implement Retry Logic: For 429 errors, use the retryAfter value to determine when to retry. For 500 errors, implement exponential backoff.