Error Handling

Understand CLI exit codes, API errors, and how to handle failures in scripts and CI/CD pipelines.

The CLI provides structured error handling with predictable exit codes following CI/CD best practices.

Exit Codes

Every command returns a numeric exit code that indicates the result:

asc apps list
echo $?  # 0 = success

Exit Code Reference

Code	Meaning	Example
`0`	Success	Command completed successfully
`1`	Generic error	Unexpected failure, network error, or unknown issue
`2`	Usage error	Invalid flags, missing required arguments, or malformed command
`3`	Authentication failure	Missing credentials, invalid API key, or permission denied
`4`	Resource not found	App, build, or resource does not exist
`5`	Conflict	Resource already exists or version conflict

HTTP Status Mapping

The CLI maps HTTP status codes to exit codes:

4xx Client Errors

Formula: 10 + (status - 400)

HTTP Status	Exit Code	Description
400 Bad Request	`10`	Invalid request parameters
401 Unauthorized	`11`	Authentication required
403 Forbidden	`12`	Permission denied
404 Not Found	`4`	Resource not found (special case)
409 Conflict	`5`	Resource conflict (special case)
422 Unprocessable	`22`	Validation error

5xx Server Errors

Formula: 60 + (status - 500)

HTTP Status	Exit Code	Description
500 Internal Server Error	`60`	API server error
502 Bad Gateway	`62`	Gateway error
503 Service Unavailable	`63`	Service temporarily unavailable

Exit codes follow a deterministic formula defined in cmd/exit_codes.go. This ensures consistent, scriptable error handling.

API Errors

The App Store Connect API returns structured error responses:

{
  "errors": [
    {
      "status": "404",
      "code": "NOT_FOUND",
      "title": "The requested resource does not exist",
      "detail": "There is no app with ID '123456789'"
    }
  ]
}

The CLI parses these errors and displays them in a human-readable format:

asc apps view --id 123456789
# Error: The requested resource does not exist: There is no app with ID '123456789'
# Exit code: 4

Well-Known Error Codes

The CLI recognizes standard App Store Connect error codes:

NOT_FOUND → Exit code 4
CONFLICT → Exit code 5
UNAUTHORIZED → Exit code 3
FORBIDDEN → Exit code 3
BAD_REQUEST → Exit code 10

These map to Go error sentinels:

// From internal/asc/errors.go
var (
    ErrNotFound     = errors.New("resource not found")
    ErrUnauthorized = errors.New("unauthorized")
    ErrForbidden    = errors.New("forbidden")
    ErrBadRequest   = errors.New("bad request")
    ErrConflict     = errors.New("resource conflict")
)

Associated Errors

Some API errors include additional details under meta.associatedErrors:

asc versions create --app APP_ID --version 1.0.0 --platform IOS
# Error: Version creation failed: The version string is invalid
# 
# Associated errors for appStoreVersion:
#   - Version string must follow semantic versioning (e.g., 1.0.0)
#   - Version 1.0.0 already exists for this app

The CLI formats these errors with clear indentation and grouping.

Error Messages

All error messages go to stderr, not stdout:

# Success: data goes to stdout
asc apps list --output json > apps.json

# Failure: error goes to stderr, stdout is empty
asc apps view --id INVALID 2> error.log
# error.log contains: "Error: The requested resource does not exist: ..."

This allows safe piping and redirection:

# Pipe only successful output
asc apps list --output json | jq '.data[0].id'

# Capture errors separately
asc apps view --id APP_ID > output.json 2> errors.log

Handling Errors in Scripts

Exit Code Checks

#!/bin/bash
set -e  # Exit on any error

asc apps list --output json > apps.json
if [ $? -eq 0 ]; then
  echo "Success: $(jq '.data | length' apps.json) apps found"
fi

Specific Error Handling

#!/bin/bash
asc apps view --id "$APP_ID" --output json > app.json
EXIT_CODE=$?

case $EXIT_CODE in
  0)
    echo "App found"
    ;;
  4)
    echo "App not found, creating..."
    asc web apps create --name "My App" --bundle-id "com.example.app" --sku "MYAPP123" --apple-id "$APPLE_ID"
    ;;
  3)
    echo "Authentication failed. Check ASC_KEY_ID and ASC_ISSUER_ID."
    exit 1
    ;;
  *)
    echo "Unexpected error (exit code: $EXIT_CODE)"
    exit 1
    ;;
esac

Retry on Transient Errors

#!/bin/bash
retry_count=0
max_retries=3

while [ $retry_count -lt $max_retries ]; do
  asc apps list --output json > apps.json
  exit_code=$?
  
  # Success
  if [ $exit_code -eq 0 ]; then
    break
  fi
  
  # Retry on 5xx errors (exit codes 60-99)
  if [ $exit_code -ge 60 ] && [ $exit_code -le 99 ]; then
    retry_count=$((retry_count + 1))
    echo "Server error, retrying ($retry_count/$max_retries)..." >&2
    sleep 5
  else
    # Non-retryable error
    echo "Fatal error (exit code: $exit_code)" >&2
    exit $exit_code
  fi
done

CI/CD Integration

GitHub Actions

- name: Fetch apps
  id: fetch_apps
  run: |
    asc apps list --output json > apps.json
  continue-on-error: true

- name: Handle errors
  if: failure()
  run: |
    echo "Failed to fetch apps (exit code: $?)"
    exit 1

GitLab CI

fetch_apps:
  script:
    - asc apps list --output json > apps.json
  allow_failure:
    exit_codes:
      - 4  # Allow not found

Makefile

.PHONY: check-auth
check-auth:
	@asc auth status --output json > /dev/null 2>&1 || \
	  (echo "Error: Authentication failed. Run 'asc auth login'"; exit 1)

.PHONY: list-apps
list-apps: check-auth
	asc apps list --output json > apps.json

Authentication Errors

Common authentication failures and solutions:

Missing Credentials

asc apps list
# Error: missing authentication. Run 'asc auth login' or 'asc auth init'
# Exit code: 1 (generic error, not 3)

Missing credentials return exit code 1, not 3. Exit code 3 is reserved for failed authentication (invalid credentials), not missing credentials.

Invalid API Key

asc apps list
# Error: unauthorized
# Exit code: 3

Solution: Verify your credentials:

asc auth status

Permission Denied

asc apps update --id APP_ID --primary-locale "en-US"
# Error: forbidden: You don't have permission to update this app
# Exit code: 3

Solution: Check your App Store Connect role and permissions.

Debugging Errors

Enable debug logging with --debug or --api-debug:

# General debug output
asc --debug apps list

# HTTP request/response debug (redacts sensitive values)
asc --api-debug apps list

Debug output goes to stderr:

asc --api-debug apps list 2> debug.log

Environment Variables

# Enable API debug for all commands
export ASC_DEBUG=api
asc apps list

# Disable debug
unset ASC_DEBUG

Error Handling Best Practices

Always Check Exit Codes

Use set -e in shell scripts or check $? after each command.

Separate stdout and stderr

Redirect errors to a log file: asc apps list 2> errors.log.

Handle Expected Errors

Exit code 4 (not found) is often expected. Handle it explicitly.

Retry Transient Errors

Retry on exit codes 60-99 (5xx server errors) with exponential backoff.

Authentication - Set up API credentials
Workflows - Error handling in multi-step workflows
Exit Codes Reference - Source code

Getting Started

Core Concepts

Guides

CI/CD Integration

Configuration

Error handling

Error Handling

Exit Codes

Exit Code Reference

HTTP Status Mapping

4xx Client Errors

5xx Server Errors

API Errors

Well-Known Error Codes

Associated Errors

Error Messages

Handling Errors in Scripts

Exit Code Checks

Specific Error Handling

Retry on Transient Errors

CI/CD Integration

GitHub Actions

GitLab CI

Makefile

Authentication Errors

Missing Credentials

Invalid API Key

Permission Denied

Debugging Errors

Environment Variables

Error Handling Best Practices

Always Check Exit Codes

Separate stdout and stderr

Handle Expected Errors

Retry Transient Errors

​Error Handling

​Exit Codes

​Exit Code Reference

​HTTP Status Mapping

​4xx Client Errors

​5xx Server Errors

​API Errors

​Well-Known Error Codes

​Associated Errors

​Error Messages

​Handling Errors in Scripts

​Exit Code Checks

​Specific Error Handling

​Retry on Transient Errors

​CI/CD Integration

​GitHub Actions

​GitLab CI

​Makefile

​Authentication Errors

​Missing Credentials

​Invalid API Key

​Permission Denied

​Debugging Errors

​Environment Variables

​Error Handling Best Practices

Always Check Exit Codes

Separate stdout and stderr

Handle Expected Errors

Retry Transient Errors

​Related

Error Handling

Exit Codes

Exit Code Reference

HTTP Status Mapping

4xx Client Errors

5xx Server Errors

API Errors

Well-Known Error Codes

Associated Errors

Error Messages

Handling Errors in Scripts

Exit Code Checks

Specific Error Handling

Retry on Transient Errors

CI/CD Integration

GitHub Actions

GitLab CI

Makefile

Authentication Errors

Missing Credentials

Invalid API Key

Permission Denied

Debugging Errors

Environment Variables

Error Handling Best Practices

Related