Error Codes vs Textual Codes

[F21]

I am building an API and would like to return responses to the client if an error has occurred.

 

I am currently using the appropriate HTTP status code, but would like to introduce my own error codes. This is particularly useful because if the client is a form and they do not want to use my returned error messages for each field, they can use the error codes and show their own messages.

 

I am currently debating between numeric codes (5000, 6000 etc) vs textual ones (ConditionNotMet, InvalidUsername) etc.

 

Textual ones are pretty self explanatory, which is a good thing. But the disadvantage is that they can be more susceptible to typos (although the same could be said with numeric codes). The other disadvantage of textual codes is that as the app gets bigger, and we get more codes, they become longer. In addition, we cannot rename an error code if it needs to be changed to reflect changes in the system.

 

What do you guys think? What do you guys use for your APIs?

[Chad Angerer]

Why not attach error messages/codes with a link to error information to your standard HTTP response codes in the body?

I'd be inclined to return standard HTTP codes but within the body produce your own messages that can be looked up or parsed based on documentation.

4xx for client errors

5xx for server errors

To me it seems like it'd be difficult to ask a "client" to parse new error codes based on changes you might make to your API as it evolves. You could return a list of default error messages and "internal codes".  This might be configurable on the server end.. or the client could map them appropriately based on their domain.  In the end the standard HTTP codes at least give direction to catch a client vs server error and handle accordingly.  

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Jørn Wildt]

You may want to go through this discussion: https://groups.google.com/forum/?fromgroups=#!searchin/api-craft/error$20wildt/api-craft/GLz_nNbK-6U/1rBRvnOE7sQJ

/Jørn

[Phil Jackson]

Hey,

HTTP code, as you're probably aware, are pretty much a solved dilemma
for the most common error cases. As for supplementing them with domain
specific errors, the following example is a reasonable one:

{
meta: {
version: 1,
status_code: 403
},
results: {
error: {
type: "KeyError",
message: "'xxx' is not a valid key for 'acmeapi'"
}
}

In ApiAxle these errors are actually being generated from a standard
node.js Error object which bubbles up through the stack when they
occur. I just decorate them with a (http) status code.

I would highly recommend avoiding magic numbers for codes they're a
total pita to maintain, you force users to have to look them up and
often they'll mean nothing to you when you're developing. Go text, no
doubt.

Cheers,
Phil

--
Apiaxle http://apiaxle.com - A free, open proxy for your API.

[sune jakobsson]

Omna, has a set of additonal codes, that we use in OneAPI.

Sent from my Windows Phone From: Phil Jackson
Sent: 09.05.2013 21:30
To: api-...@googlegroups.com
Subject: Re: [api-craft] Error Codes vs Textual Codes

[Jørn Wildt]

I just finished a blog post with some more in-depth discussion about error handling in web APIs (based on input from this list and other web resources): http://soabits.blogspot.dk/2013/05/error-handling-considerations-and-best.html.

/Jørn