Error Codes

Complete reference for all error codes returned by Big Picture APIs.

Standard Error Response

All error responses follow this format:

{
  "error": "error_code",
  "message": "Human-readable error message",
  "details": {
    "field": "additional error details"
  },
  "request_id": "req_abc123"
}

Error Code Reference

Error Code	HTTP Status	Description
unauthorized	401	Missing or invalid authentication token
forbidden	403	Insufficient permissions
token_expired	401	Authentication token expired
validation_error	400	Request validation failed
invalid_format	400	Invalid data format
missing_required_field	400	Required field missing
not_found	404	Resource not found
conflict	409	Resource conflict (e.g., duplicate)
rate_limit_exceeded	429	Rate limit exceeded
internal_error	500	Internal server error
service_unavailable	503	Service temporarily unavailable
timeout	504	Request timeout
policy_violation	400	Policy validation failed
version_conflict	409	Version conflict
lease_denied	403	License lease denied
seat_not_assigned	403	Subject does not have an assigned seat (explicit mode only)
seat_limit_exceeded	403	Maximum seats already in use (automatic mode)
duplicate_seat_assignment	409	Subject already has a seat for this entitlement
invalid_seat_assignment_mode	400	Entitlement uses automatic seat assignment

Authentication Errors

unauthorized (401)

Missing or invalid authentication token.

Response:

{
  "error": "unauthorized",
  "message": "Authentication required",
  "request_id": "req_abc123"
}

forbidden (403)

Insufficient permissions for the requested operation.

Response:

{
  "error": "forbidden",
  "message": "Insufficient permissions",
  "details": {
    "required_scope": "ci:write"
  },
  "request_id": "req_abc123"
}

token_expired (401)

Authentication token has expired.

Response:

{
  "error": "token_expired",
  "message": "Authentication token expired",
  "request_id": "req_abc123"
}

Validation Errors

validation_error (400)

Request validation failed.

Response:

{
  "error": "validation_error",
  "message": "Request validation failed",
  "details": {
    "field": "version",
    "reason": "Invalid version format"
  },
  "request_id": "req_abc123"
}

invalid_format (400)

Invalid data format.

Response:

{
  "error": "invalid_format",
  "message": "Invalid data format",
  "details": {
    "field": "version",
    "expected": "semver format (e.g., 1.2.3)"
  },
  "request_id": "req_abc123"
}

missing_required_field (400)

Required field missing from request.

Response:

{
  "error": "missing_required_field",
  "message": "Required field missing",
  "details": {
    "field": "productId"
  },
  "request_id": "req_abc123"
}

Resource Errors

not_found (404)

Resource not found.

Response:

{
  "error": "not_found",
  "message": "Resource not found",
  "details": {
    "resource_type": "release",
    "resource_id": "rel_abc123"
  },
  "request_id": "req_abc123"
}

conflict (409)

Resource conflict, typically a duplicate or constraint violation.

Response:

{
  "error": "conflict",
  "message": "Resource conflict",
  "details": {
    "reason": "Release with version 1.2.3 already exists"
  },
  "request_id": "req_abc123"
}

version_conflict (409)

Version conflict in release creation or policy update.

Response:

{
  "error": "version_conflict",
  "message": "Version conflict",
  "details": {
    "product_id": "prod_abc123",
    "version": "1.2.3",
    "existing_release_id": "rel_xyz789"
  },
  "request_id": "req_abc123"
}

Rate Limiting

rate_limit_exceeded (429)

Rate limit exceeded.

Response:

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Retry after 2024-01-15T10:31:00Z",
  "details": {
    "retry_after": 60,
    "limit": 1000,
    "remaining": 0
  },
  "request_id": "req_abc123"
}

Headers:

• X-RateLimit-Limit: 1000
• X-RateLimit-Remaining: 0
• X-RateLimit-Reset: 1640995200
• Retry-After: 60

Server Errors

internal_error (500)

Internal server error.

Response:

{
  "error": "internal_error",
  "message": "An internal error occurred",
  "request_id": "req_abc123"
}

service_unavailable (503)

Service temporarily unavailable.

Response:

{
  "error": "service_unavailable",
  "message": "Service temporarily unavailable",
  "details": {
    "retry_after": 30
  },
  "request_id": "req_abc123"
}

timeout (504)

Request timeout.

Response:

{
  "error": "timeout",
  "message": "Request timeout",
  "request_id": "req_abc123"
}

Business Logic Errors

policy_violation (400)

Policy validation failed.

Response:

{
  "error": "policy_violation",
  "message": "Policy validation failed",
  "details": {
    "policy_id": "policy_abc123",
    "reason": "Version 1.2.3 is blocked"
  },
  "request_id": "req_abc123"
}

lease_denied (403)

License lease denied.

Response:

{
  "error": "lease_denied",
  "message": "License lease denied",
  "details": {
    "reason": "No available licenses",
    "entitlement_id": "ent_abc123"
  },
  "request_id": "req_abc123"
}

Licensing Errors

seat_not_assigned (403)

Subject does not have an assigned seat (explicit mode only).

Response:

{
  "error": "seat_not_assigned",
  "message": "Subject does not have an assigned seat",
  "details": {
    "subject_type": "user",
    "subject_id": "user@example.com",
    "entitlement_id": "ent_abc123"
  },
  "request_id": "req_abc123"
}

seat_limit_exceeded (403)

Maximum seats already in use (automatic mode).

Response:

{
  "error": "seat_limit_exceeded",
  "message": "Maximum seats already in use",
  "details": {
    "entitlement_id": "ent_abc123",
    "max_seats": 10,
    "active_seats": 10
  },
  "request_id": "req_abc123"
}

duplicate_seat_assignment (409)

Subject already has a seat for this entitlement.

Response:

{
  "error": "duplicate_seat_assignment",
  "message": "Subject already has a seat for this entitlement",
  "details": {
    "subject_type": "user",
    "subject_id": "user@example.com",
    "entitlement_id": "ent_abc123",
    "existing_seat_assignment_id": "seat_xyz789"
  },
  "request_id": "req_abc123"
}

invalid_seat_assignment_mode (400)

Entitlement uses automatic seat assignment.

Response:

{
  "error": "invalid_seat_assignment_mode",
  "message": "Entitlement uses automatic seat assignment",
  "details": {
    "entitlement_id": "ent_abc123",
    "seat_assignment_mode": "automatic"
  },
  "request_id": "req_abc123"
}