I have been in charge of developing and maintaining integration with Facebook Marketing API for more than half a year now. It has been nothing but the pain so far. I decided to come from the shadow and list some of the things I encountered so you know how big companies develop their APIs with complete disrespect for developers. BE WARNED! If you can avoid integrating with Facebook, don't integrate.

1. Documentation

At the first sight, Facebook docs are really nice and clean. And they are pretty good. However, the feature I needed is Custom Audiences. And here's a funny thing: there is an intro to Custom Audiences available in the docs, however, there is no link to actual endpoint reference there. This does not mean that the document does not exist. It's there, but you can only access it from Google or their internal search. Took me over a week to accidentally stumble upon that.

2. Versioning

When you go to Graph API's changelog page you can see a beautiful table listing how long different versions of API should be available. And it's nice because the grace period is really long - two years after the introduction of a newer version. This is the way it should be...

... except it's not exactly true. All requests to Facebook API must be done via an application created in their Development Portal. And when the app is created, it can only use API in the most recent version at the time of creation or newer. While it sounds like something making sense, it not exactly is in our case. We only serve as a proxy between a real customer (who are in charge of their Ad Account, Application etc., they just give us a correct access token). This means that we always need to be on the most recent version of API because a new app can be created at any time by the customer.

While it might be OK for Facebook to not support our use case, it could really be mentioned clearly in the docs. I'd waste at least two weeks less trying to figure out why requests are failing only for part of customers.

3. Error messages

It happened at some point that we introduced a regression – when creating a new Custom Audience, we sent a payload with empty name parameter. What the result should be? Some validation error, you think? I thought that too. That's why I checked many permission-related things and did not look at the payload after seeing an error message like this:

{"message": "(#2654) Failed to create custom audience", "type": "OAuthException", "code": 2654, "fbtrace_id": "xxxxyyyy"}

It's pretty obvious that when you get OAuthException it means that a required field in the payload is empty. Right? RIGHT?

Best thing? I actually reported that to Facebook. Their response? "Since this isn't really a bug (the error is intended), I can't assign it from this report but I will be sure to pass your feedback to the relevant engineering team to at least get their thoughts on this". Yep. That's a WONTFIX.

4. Temporary removing things

Around Christmas last year (yep, the best time for huge breaking changes) Facebook removed an estimated count for custom audiences in their system. What is it? Basically, when you upload a list of users to Facebook Marketing API, you never know how many users will be matched with the Facebook database. If you upload 1000 hashed emails, it may happen that all will be matched, or zero, or any number between. Approximate count served the purpose of letting you know how many people were more or less matched.

So, suddenly on Christmas it started to always show -1. This was a "temporary fix" because apparently some people were using those counts for something fishy and illegal. The fix was not announced anywhere. People came back from their holidays and started receiving frightened calls from customers that their audiences stopped work and show -1 as size.

Go ahead, try to explain to them what I wrote above.

Of course, now it's 8 months later and this temporary workaround is still in force (I think they no longer refer to it as temporary at least).

5. Changing API without any notice

But lately they really outdid themselves.

Sometimes you need to delete people from your custom audience. Oh, did I say "sometimes"? You need to do it all the time because people opt-out from your system and you need to delete them from all synchronizations. They can also revoke a consent or anything. There are literally tens of reasons to do it.

On the other hand, audiences need to have a correct size to be operational on Facebook side. The reason for that is to avoid "sniping" users with very specific and precise ads directed to one or two persons. However, as you have read in point 4, you never know how big your audience actually is. When it happens that its size drop below "safety threshold", the audience becomes unusable and campaigns based on it stop, until you add some users again, when it resumes operation.

Sounds like it makes sense? It did. But not anymore.

According to this report it stopped working like that at August 8th. Now when you are deleting users and it would make its size too small, few things happen:

• Request returns error. Of course it's Facebook, so the error is Permissions error
• It also returns "error_subcode": 1870047. It's not mentioned anywhere, especially not on a page with all error codes that API might return.
• Request fails, meaning that users are actually not deleted. They are still there, violating your agreements.

As you probably might have guessed, the report was quickly closed, because it's "valid behaviour".

Maybe they introduced that with new API version? No, I don't think so. The last version was released on July 26th, so almost two weeks earlier. Also, the changelog does not mention any of that.

Yes. The request which was perfectly fine started to return error overnight. And no one seems to see a problem on Facebook side. This is a stable API after all.

Final remark

If you have a chance to talk your managers out of integrating with Facebook, DO IT AT ALL COSTS. You'll thank me later.