Feedback on documented API: error codes

The documentation isn't officially released yet, but I have some feedback anyway:

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.