Errors and limits
Refusals that name their own cause, rate limits, and how to pace yourself.
A refusal always names its own cause. You should never have to guess whether you have a permissions problem or a hierarchy problem:
{
"error": "insufficient_scope",
"message": "This key has contacts:read. This call needs contacts:write.",
"needed": "contacts:write"
}
{
"error": "unknown_sub_account",
"message": "No sub-account with that id belongs to \"Your Agency\". This is a
hierarchy problem, not a scope problem — adding scopes will not
change it."
}Writes report every invalid field at once under fields, rather than one per round trip. Learning an endpoint by bisection is not a thing anyone should have to do.
Rate limits
100 requests per 10 seconds, and 200,000 per day — counted per credential per sub-account, so installing on more sub-accounts does not divide your allowance.
Every response carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Daily-Remaining, so you can pace yourself instead of finding the wall by hitting it.