Reporting API

Errors & troubleshooting

Reporting API v2 errors returned from the v2 controller’s exception filter use RFC 9457 Problem Details as application/problem+json:

{
  "type": "VALIDATION_ERROR",
  "title": "Validation Error",
  "detail": "Maximum of 50 campaignIds allowed."
}
Field Use
type Machine-readable code — branch in code on this value when present.
title Short static label for the type.
detail Human-readable explanation for this request — log for operators; avoid showing raw secrets.

There is no status field in the JSON body; rely on the HTTP status line.

Domain type values

These are defined in the v2 reporting stack and emitted on controller-handled errors:

type HTTP When it happens What to do
VALIDATION_ERROR 400 class-validator failures, bad query shape, date range > 2 years, >50 campaignIds, etc. Fix parameters; read detail.
INVALID_SORT_PROPERTY 400 Unknown sortProperty for the endpoint Choose a value from Querying the API.
RESOURCE_NOT_FOUND 404 Mapped service “not found” errors Verify IDs / route.
INTERNAL_ERROR 500 (default) Unexpected failure OR some permission failures mapped internally Retry with backoff; contact support with timestamp + request id (if provided by gateway).

403 edge cases: Some forbidden paths may surface as INTERNAL_ERROR with title Forbidden depending on the upstream ServiceError mapping. Prefer HTTP status + logs, and avoid coupling only to type for authz until the map is simplified in a future release.

Example bodies

Invalid sortProperty

{
  "type": "INVALID_SORT_PROPERTY",
  "title": "Invalid Sort Property",
  "detail": "Invalid sortProperty 'badField' for /posts/performance. Valid values are: cpe, cpm, engagementRate, engagements, estimatedValueGenerated, impressions, paidCpe, paidCpm, paidEngagementRate, paidEngagements, paidImpressions, postDate"
}

Too many campaign IDs

{
  "type": "VALIDATION_ERROR",
  "title": "Validation Error",
  "detail": "Maximum of 50 campaignIds allowed."
}

Date range exceeds two years

{
  "type": "VALIDATION_ERROR",
  "title": "Validation Error",
  "detail": "Date range cannot exceed 2 years."
}

Authentication and gateway errors

401 Unauthorized and 403 Forbidden are usually produced outside this filter (JWT validation, API gateway). Bodies may not match the table above. Treat 401 as “fetch a new JWT”; treat 403 as “verify instance scope / roles.”

Rate limiting (future)

429 Too Many Requests is expected when server-side enforcement lands (Q2 2026 target). Implement backoff today. See Rate limiting.

Example (illustrative once enforced)

{
  "type": "VALIDATION_ERROR",
  "title": "Validation Error",
  "detail": "Rate limit exceeded. Retry after 2026-06-01T12:00:00Z"
}

Actual type for throttling will be confirmed at launch.

Retry strategy

HTTP Retry? Notes
400 No Fix input.
401 No (first refresh token) Re-authenticate once, then retry original request.
403 No Permission / scope.
404 Usually no Broken path or missing resource.
429 Yes Exponential backoff + respect Retry-After.
500 / 502 / 503 Yes Transient; cap attempts.

Pseudocode — exponential backoff

attempt = 0
while attempt < maxAttempts:
  response = httpCall()
  if response.status in [500, 502, 503, 429]:
    sleep min(cap, base * 2**attempt + jitter)
    attempt += 1
    continue
  return response

Logging guidance

  • Log type, HTTP status, endpoint, and redacted query params.
  • Prefer detail for support tickets; pair with any request / trace IDs your gateway adds.

Support

Need help with the Reporting API? Contact support through these channels:

Need Channel
Credentials & access Your Later / Mavrck account team or urvash.chheda@later.com
API bugs / unexpected 5xx Email urvash.chheda@later.com with timestamps (UTC), request path, and redacted params
Product how-tos Later Influence Help Center

When reporting an issue, include:

  • HTTP status code and error type / detail from the response
  • Approximate UTC timestamp of the request
  • Request path and redacted query parameters
  • Instance IDs you were querying (if applicable)
  • Any request / trace IDs provided by the gateway

Enterprise customers: Request dedicated onboarding sessions (architecture review, pagination patterns, warehouse integration) through your Customer Success Manager or urvash.chheda@later.com.

Related pages

Previous
Migration from v1