Feedback on documented API: error codes


85 Goblin Warrior
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.
Web & Mobile Team
As I said here:

07/03/2011 03:27 PMPosted by Straton
The caveat is that there are some changes and edits that have not been pushed yet, so please don't provide feedback or comments until the documentation is official up.

Locking this thread.
This topic is locked.

Please report any Code of Conduct violations, including:

Threats of violence. We take these seriously and will alert the proper authorities.

Posts containing personal information about other players. This includes physical addresses, e-mail addresses, phone numbers, and inappropriate photos and/or videos.

Harassing or discriminatory language. This will not be tolerated.

Forums Code of Conduct

Report Post # written by

Explain (256 characters max)
Submit Cancel