Report that a matched segment's client-side re-upload failed

POST

/v1/segments/{id}/upload-failed

curl --request POST \
  --url https://dev-api.infiniteaudience.ai/v1/segments/example/upload-failed \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "audience_id": "example", "reason": "example" }'

• Development API Server

Called when a matched segment’s re-upload (kicked off by POST /v1/segments/{id}/refresh or POST /v1/audiences/{id}/refresh) fails client-side before ever reaching storage — e.g. a browser-side network or CORS failure on the presigned upload PUT. The async pipeline that would normally fail the segment never starts in that case, since no upload ever arrived, so without this call the segment (and any linked audience) would otherwise stay pending until a much slower backstop eventually catches it.

Idempotent — a no-op (already_resolved: true) if the segment has already moved past pending (e.g. the upload actually succeeded). Only valid for matched-subtype segments. Requires ‘purchase’ scope.

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

string

Segment document ID.

Request Body

Media typeapplication/json

object

audience_id

Optional linked audience to also mark failed, in addition to the segment’s own linked audience (if any).

string

reason

Human-readable failure reason.

string

<= 500 characters

Example^generated

{
  "audience_id": "example",
  "reason": "example"
}

Responses

200

Segment (and any linked audience) marked failed, or already resolved.

Media typeapplication/json

object

ok

required

boolean

already_resolved

required

True if the segment had already moved past pending before this call.

boolean

Example

{
  "ok": true,
  "already_resolved": false
}

400

NOT_A_MATCHED_UPLOAD — only matched-subtype segments have an upload to report as failed.

Media typeapplication/json

object

error

required

string

code

required

string

Allowed values: NOT_A_MATCHED_UPLOAD

message

required

string

Example

{
  "error": "Bad Request",
  "code": "NOT_A_MATCHED_UPLOAD",
  "message": "Only matched-subtype segments have an upload to report as failed."
}

401

Missing or invalid Bearer token. Obtain one via POST /v1/auth/token. When a token was supplied but rejected, code distinguishes TOKEN_EXPIRED (the token’s lifetime has passed — request a new one via POST /v1/auth/token and retry) from TOKEN_INVALID (malformed or revoked — re-authenticate).

Media typeapplication/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

key

additional properties

any

Examples

{
  "error": "Unauthorized: Missing or invalid Authorization header"
}

{
  "error": "Unauthorized",
  "code": "TOKEN_EXPIRED",
  "message": "Your session has expired. Please sign in again."
}

403

Token is valid but lacks the required scope for this endpoint. Check the endpoint description for the required scope (discovery, purchase, or account).

Media typeapplication/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

key

additional properties

any

Examples

Examplemissing_scope

{
  "error": "SCOPE_REQUIRED",
  "message": "This endpoint requires the purchase scope."
}

404

Resource not found or not accessible to the calling org.

Media typeapplication/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

key

additional properties

any

Examples

Examplenot_found

{
  "error": "Audience not found"
}