POST /pipeline Returns 201 When No Actual Workflow Is Triggered

[TheMetalCode]

Example: In my org for certain projects we have a special workflow that is API triggered (via the POST /pipeline endpoint with pipeline params) and reserved for only certain branches (filtered by regex in the .circleci/config.yml for affected projects).

Today we had an issue where somebody was trying to trigger that workflow for a branch that didn't match the filter, and my API wrapper didn't catch it because it wasn't an error response from the API, but rather a 201 instead of the usual 202.

Because the response code differs, we seem to have some ability to discern when the call actually launched a workflow and when it did not. My view: a reasonable API consumer expects a workflow to be actually launched when a successful response code is returned, and if it isn't, they would want an error response to alert them to potentially update their .circleci/config.yml.

Right now I'm in the somewhat uncomfortable position of needing to handle a 201 as a failure, which just feels wrong.

Any chance we could return an error in this case?

[sulami]

Not sure right now about the error response, let me get back to you on Monday, but I can tell you that we actually just swapped the response code to 201 for the happy path, so it doesn’t reflect a failure. You should not be seeing any 202s on this route going forward.

[TheMetalCode]

Ahhh gotcha...did that just happen within the last day or so? That might explain why it was 202 before and 201 today and I might have just wrongly assumed it was due to whether or not the workflow actually launched.

[sulami]

Yes, I believe that was yesterday (EU time).

[TheMetalCode]

Ok, I've been able to confirm so I'll just expect 201s for now. I'd still be interested to know if a "successful" call that does not actually trigger workflows could potentially become an error but more than willing to wait until Monday (or whenever) for that.

[sulami]

Sorry for the delay. I had a look and due to the asynchrounous nature of pipeline triggering, there's currently no way to know at trigger time whether any workflows will be launched successfully.

That being said, we are looking at deprecating the current "error workflows" which run to display your error in a job (you've probably seen one at some point, the ones that say "don't rerun this workflow"), and making pipeline errors a more first-class entity. They will then also get their own place in the new UI that's currently in preview. With these you can probably streamline your automation to look out for these errors once your config has been processed.

I don't think we have a concrete timeline for this yet, I'm personally hoping for this quarter though. If you have any thoughts/ideas/wishes/etc., we welcome input to aide our design process.