Skip to content

Standardize Execution API error responses to RFC 9457#67286

Open
23tae wants to merge 3 commits into
apache:mainfrom
23tae:feat-execution-api-rfc9457
Open

Standardize Execution API error responses to RFC 9457#67286
23tae wants to merge 3 commits into
apache:mainfrom
23tae:feat-execution-api-rfc9457

Conversation

@23tae
Copy link
Copy Markdown
Contributor

@23tae 23tae commented May 21, 2026

This PR standardizes the Airflow Execution API error responses to follow the RFC 9457 (Problem Details for HTTP APIs) specification.

Description

Exceptions in the Execution API are caught at the FastAPI route boundary in task_instances.py and re-raised as standard HTTPExceptions. Airflow's core API framework then automatically formats these into RFC 9457 compliant JSON.

Error Response Examples

This PR demonstrates two key improvements in error handling:

Case 1: Upgrading plain string messages to structured objects

Before:

{
  "detail": "Database error occurred"
}

After:

{
  "detail": {
    "type": "about:blank",
    "title": "Internal Server Error",
    "detail": "Database error occurred"
  }
}

Case 2: Standardizing dictionaries while retaining custom context

Before:

{
  "detail": {
    "reason": "running_elsewhere",
    "message": "TI is already running elsewhere",
    "current_hostname": "worker-1",
    "current_pid": 12345
  }
}

After:

{
  "detail": {
    "type": "about:blank",
    "title": "Conflict",
    "detail": "TI is already running elsewhere",
    "reason": "running_elsewhere",
    "current_hostname": "worker-1",
    "current_pid": 12345
  }
}

Verification Results

I have verified the changes using prek and breeze.

  • Static Checks (Prek): Passed
  • Unit Tests (Breeze): Passed

closes: #62107


Was generative AI tooling used to co-author this PR?
  • Yes

Generated-by: Antigravity following the guidelines


  • Read the Pull Request Guidelines for more information. Note: commit author/co-author name and email in commits become permanently public when merged.
  • For fundamental code changes, an Airflow Improvement Proposal (AIP) is needed.
  • When adding dependency, check compliance with the ASF 3rd Party License Policy.
  • For significant user-facing changes create newsfragment: {pr_number}.significant.rst, in airflow-core/newsfragments. You can add this file in a follow-up commit after the PR is created so you know the PR number.

@23tae 23tae requested review from amoghrajesh, ashb and kaxil as code owners May 21, 2026 15:05
@boring-cyborg boring-cyborg Bot added area:API Airflow's REST/HTTP API area:task-sdk labels May 21, 2026
@ashb
Copy link
Copy Markdown
Member

ashb commented May 21, 2026

Status is moot in the response body -- that's already included in the HTTP response and shouldn't be duplicated.

@23tae 23tae force-pushed the feat-execution-api-rfc9457 branch from 8f8d874 to 4fd579c Compare May 22, 2026 00:24
@23tae
Copy link
Copy Markdown
Contributor Author

23tae commented May 22, 2026

Status is moot in the response body -- that's already included in the HTTP response and shouldn't be duplicated.

@ashb Thanks for the feedback! You're right—since the status code is already in the HTTP response, having it in the body is redundant.

I've removed the status field from the error responses and updated the tests accordingly.

Before:

{
  "detail": {
    "type": "about:blank",
    "title": "Internal Server Error",
    "status": 500,
    "detail": "Database error occurred"
  }
}

After:

{
  "detail": {
    "type": "about:blank",
    "title": "Internal Server Error",
    "detail": "Database error occurred"
  }
}

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:API Airflow's REST/HTTP API area:task-sdk

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Pass a RFC 9457 compliant error message in "detail" field of HTTPException to provide more information about the error

2 participants