#1 - July 4, 2011, 12:03 a.m.
The API, I feel, should make more use of HTTP response codes. Not Found is 404, every other error is 500, which should generally be used only for a server-side error.
I would suggest using the following codes:
Invalid application, Invalid application permissions, invalid application signature - 401 Unauthorized
Access denied - 403 Forbidden
Throttled - 503 Service Unavailable (preferably WITH a Retry-After header!)
Invalid authentication header - 400 Bad Request
The other two, not found and internal server error, are appropriate as 404 and 500 respectively :-)
The reason for this is ease of client error handling, without keeping a set of strings that may be returned, particularly if those strings wind up being localised. In particular, receiving a 500 would mean you just need to wait a bit then retry, while a 401 means you need to flag to the operator that there's a credentials problem, a 403 means the operator needs to go to layer 8 to fix the issue, and a 503 means you should increase your per-request delay.
Most notable is that all 4xx errors are not recoverable, and require operator intervention, but all 5xx errors are recoverable with time. In particular, getting a 503 with a Retry-After would let a client fine tune its back-off behaviour.
