Errors

The API uses conventional HTTP status codes and returns a single, consistent error envelope for every non-2xx response.

Error envelope

{
  "type": "https://api.adbridge.ai/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Network 7Hb2Kp9QvL3mNx0R8tZ4 was not found"
}

Field	Description
type	A URI identifying the error type.
title	A short, human-readable summary.
status	The HTTP status code.
detail	A human-readable explanation of this specific occurrence.

Status codes

Status	When it happens
400 Bad Request	Invalid input — a missing/blank required field, a bad enum value, or a malformed pagination cursor.
401 Unauthorized	Missing, malformed, invalid, revoked, or expired API key. See Authentication.
403 Forbidden	The key is valid but not authorized for this network or at this role.
404 Not Found	The resource does not exist — or is not visible to your key (ids are not leaked).
409 Conflict	The write conflicts with current state: an optimistic-lock version mismatch, or a guarded transition (e.g. removing the last active admin, or accepting an offer that is no longer open). Re-fetch and retry.
429 Too Many Requests	A rate limit was hit. Honor the Retry-After response header (seconds) before retrying.
500 Internal Server Error	An unexpected server error. Safe to retry idempotently.
502 Bad Gateway	An upstream dependency (e.g. voice synthesis) failed. Retry later.

Concurrency: optimistic locking

Writes are optimistically locked. If a resource changed between your read and your write, the update returns 409 Conflict. Re-fetch the resource and re-apply your change.

Idempotency

POST requests can be made idempotent by sending an Idempotency-Key header with a unique value (e.g. a UUID) per logical operation. If a request with the same key is retried (a network blip, a client timeout), the original response is replayed instead of performing the operation twice. A replayed response carries the Idempotent-Replayed header. Reuse the same key only for the exact same request.

cURL

curl -X POST https://api.adbridge.ai/v1/networks/7Hb2Kp9QvL3mNx0R8tZ4/campaigns \
  -H "Authorization: Bearer $ADBRIDGE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "Spring Launch 2026", "advertiser_id": "7Hb2Kp9QvL3mNx0R8tZ4"}'

Python

import os
import uuid
import requests

resp = requests.post(
    "https://api.adbridge.ai/v1/networks/7Hb2Kp9QvL3mNx0R8tZ4/campaigns",
    headers={
        "Authorization": f"Bearer {os.environ['ADBRIDGE_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"name": "Spring Launch 2026", "advertiser_id": "7Hb2Kp9QvL3mNx0R8tZ4"},
)
print(resp.status_code, resp.headers.get("Idempotent-Replayed"))

Node.js

import { randomUUID } from "node:crypto";

const resp = await fetch(
  "https://api.adbridge.ai/v1/networks/7Hb2Kp9QvL3mNx0R8tZ4/campaigns",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.ADBRIDGE_API_KEY}`,
      "Idempotency-Key": randomUUID(),
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Spring Launch 2026",
      advertiser_id: "7Hb2Kp9QvL3mNx0R8tZ4",
    }),
  },
);
console.log(resp.status, resp.headers.get("Idempotent-Replayed"));

Go

body := strings.NewReader(`{"name":"Spring Launch 2026","advertiser_id":"7Hb2Kp9QvL3mNx0R8tZ4"}`)

req, _ := http.NewRequest(http.MethodPost,
    "https://api.adbridge.ai/v1/networks/7Hb2Kp9QvL3mNx0R8tZ4/campaigns", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("ADBRIDGE_API_KEY"))
req.Header.Set("Idempotency-Key", uuid.NewString()) // github.com/google/uuid
req.Header.Set("Content-Type", "application/json")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()
fmt.Println(resp.Status, resp.Header.Get("Idempotent-Replayed"))

Java

String body = "{\"name\":\"Spring Launch 2026\",\"advertiser_id\":\"7Hb2Kp9QvL3mNx0R8tZ4\"}";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.adbridge.ai/v1/networks/7Hb2Kp9QvL3mNx0R8tZ4/campaigns"))
    .header("Authorization", "Bearer " + System.getenv("ADBRIDGE_API_KEY"))
    .header("Idempotency-Key", UUID.randomUUID().toString())
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode() + " " + response.headers().firstValue("Idempotent-Replayed"));