Overview - Bedrock

All errors follow the Problem Details format (RFC 7807). The type field is a URI that links to a page describing the problem.

Error Format

{
  "type": "https://docs.bedrock.cv/errors/validation",
  "title": "Validation error",
  "status": 400,
  "detail": "One or more request fields are invalid.",
  "code": "VALIDATION_ERROR",
  "requestId": "req_01JABCD123",
  "errors": {
    "overlay_id": ["Required field"]
  }
}

Field	Type	Description
`type`	string	URI identifying the problem type
`title`	string	Short summary of the problem
`status`	integer	HTTP status code
`detail`	string	Human-readable explanation
`code`	string	Machine-readable error code
`requestId`	string	Unique request identifier for support
`errors`	object	Field-level validation errors (when applicable)

Error Types

Type	Status	Code	Description
`/errors/validation`	400	`VALIDATION_ERROR`	Invalid request fields
`/errors/authentication`	401	`UNAUTHORIZED`	Missing or invalid API key
`/errors/insufficient-credits`	402	`INSUFFICIENT_CREDITS`	Not enough credits
`/errors/authorization`	403	`FORBIDDEN`	Key lacks access to resource
`/errors/not-found`	404	`NOT_FOUND`	Resource doesn’t exist
`/errors/rate-limit`	429	`RATE_LIMITED`	Too many requests

Handling Errors

Check the code field to determine how to respond:

response = requests.post(url, headers=headers, json=data)

if response.status_code >= 400:
    error = response.json()

    if error["code"] == "RATE_LIMITED":
        time.sleep(int(response.headers.get("Retry-After", 60)))
        retry()
    elif error["code"] == "VALIDATION_ERROR":
        fix_request(error["errors"])
    elif error["code"] == "INSUFFICIENT_CREDITS":
        top_up_credits()
    else:
        raise Exception(error["detail"])

Request ID

Every response includes a requestId. Include it when contacting support:

X-Request-Id: req_01JABCD123