12 codes

Errors

When a request cannot be completed, the API returns the appropriate HTTP status code and a JSON body containing an error object:

Error body

{
  "log_id": "...",
  "timestamp": "...",
  "error": {
    "code": "BRAND_ID_REQUIRED",
    "message": "...",
    "details": { ... }
  }
}

The error.code field is a constant your application can test to handle each condition; message is a description of the problem, and details provides condition-specific context. The following codes are returned:

Codes

Code	HTTP	Meaning
INVALID_API_KEY	401	The `x-api-key` header is missing, malformed, or doesn't match a known key.
EXPIRED_API_KEY	401	The key was valid but its expiration date has passed. Issue a new key.
REVOKED_API_KEY	401	The key was explicitly revoked. Issue a new key.
INVALID_ID	400	A path or query id (`brand_id`, `creator_id`, content id) is not a valid identifier.
NOT_FOUND	404	The resource does not exist or is outside this api key's scope.
VALIDATION_ERROR	400	A query parameter has the wrong type, an unknown sort field, or otherwise failed validation. `details` lists the offending fields.
BRAND_ID_REQUIRED	400	A brand-scoped filter or sort was used without supplying `brand_id`. `details.blocked_by` names the parameters that triggered it.
PERMISSION_DENIED	403	The api key cannot access the requested brand or resource.
RATE_LIMIT_EXCEEDED	429	A quota limit was exceeded. `details.scopes` names the group(s) that were hit and `details.retry_after_seconds` is how long to wait before retrying.
NOT_ACCEPTABLE	406	The requested response media type cannot be served (the API only emits `application/json`).
SERVICE_UNAVAILABLE	503	The request took too long and was stopped. Narrow the date window or pass `brand_id`, then retry.
INTERNAL_ERROR	500	Something went wrong on our side. Include `log_id` when filing a support ticket.

The error body

The same three attributes come back on 400, 401, 403, 404, 406, 429, 500 and 503, so one handler covers every failure.

Quote the log_id when you report a problem. It names the one request in our logs, and it is the fastest thing to answer with.

Attributes

log_idstringRequired

timestampstring(date-time)Required

errorobjectRequired