I'm implementing an API. The API accepts/returns JSON content type.
Now, suppose that the data submitted by some POST request is not valid, like a missing attribute, or a duplication exists for the same data.
What is the standard HTML response code in that case?
The error lies on the client side, so you want to use a 4xx status code. I'd go with 400 - Bad Request:
The request could not be understood by
the server due to malformed syntax.
The client SHOULD NOT repeat the
request without modifications.
There are two answers:
If you have submitted a form, just return 200 - OK with HTML explaining why the object was not created.
If you have an API you should use the following
200 OK
When the request was OK and returned the proper data.
201 CREATED
The call was successful and the new object created.
400 BAD REQUEST
Invalid request URI
Invalid HTTP Header
Receiving an unsupported, nonstandard parameter
Receiving an invalid HTTP Message Body
401 UNAUTHORIZED
Authorization problems. E.g. wrong API key, etc.
403 FORBIDDEN
Properly authorized, but not allowed.
404 NOT FOUND
The resource does not exist (e.g. on Read or Update)
405 METHOD NOT ALLOWED
Use in situations that a given REST method is not allowed. E.g. a POST on a single resource, or a DELETE on the entire collection of resources.
409 CONFLICT
When an update fails, send "Conflict" to allow the client side to resolve the conflict themselves and retry.
500 INTERNAL SERVER ERROR
Internal error. This is the default code that is used for all unrecognized errors.
501 NOT IMPLEMENTED
Use for expected, but not yet implemented features.
The closest i can find would be 400 Bad Request.
As Ariejan said you should base your API in the HTTP codes already defined. If you want to send a error message the best way should be not use the HTTP message, but better include the message in the response body, JSON formatted.
422 Unprocessable Entity (see RFC 4918, Section 11.2)
Related
I have setup a mock server in Postman.
For a request X, I have added 2 examples (responses)
200 Success Response
400 Bad request
When I use x-mock-response-code I am able to get the appropriate response.
But when I dont use the x-mock-response-code, I am always getting 400 Bad Request. I am expecting 200 by default. But its not happening.
Do I need to add some thing to example response ? I tried to change example name as Default but no use..
If your example requests are identical, Postman will deterministically return the response for one of them. There is no concept of 'default' examples at this time.
If you want a particular response to be returned, make sure your example requests are not identical and only one example request matches the request you are sending.
Or use the x-mock-response-code header as you are already doing.
I'm implementing user registration for a Web Service.
When somebody wants to register an account, my WS sends an activation link to his/her mail. Until this link is clicked, user account is not activated (but the info is persisted in database, so the resource exists).
So my question is, if you try to register the same mail several times, you will get a 409 CONFLICT code. But there are two scenarios right there:
User account pending on confirmation
User already registered and activated
I would like to know what is the right approach. Should I "invent" an HTTP status 4XX to distinguish them, or send 409 with a JSON with info? other solutions?
Thx!
EDIT:
I have found this response -> https://stackoverflow.com/a/3290369/1171280 where Piskvor suggest to use 409 status and request header to explain the reason why it failed and/or body. Which one? header? body? both?
What do you think?
EDIT 2:
HTTP status + body with detailed error (with machine-parseable codes even) is OK, Twitter does that (https://dev.twitter.com/docs/error-codes-responses) and RESPECT :) . But I still doubt with 403 vs 409... :S
Pending account is a special type of a user account, so I think both accounts (already registered and pending) are same in the context of your question. You should return 409 in both cases. For the REST API both are same cases because that resource already exists in the system.
Regarding your updated question, I would suggest using body (JSON) to send out error(s) instead of using a custom HTTP header to explain the reason why the call failed. Reason is that in the body can you have multiple error messages (each one as a separate JSON object/array element) where as in the header you can have only one (though you can split based on some character). Other reason is that you can have one generic error handling method which looks for an "error" object in the JSON instead of looking for different custom headers for each failure scenario.
HTTP codes:
403 - The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be
repeated.
409 - The request could not be completed due to a conflict with the current state of the resource. This code is only allowed in
situations where it is expected that the user might be able to resolve
the conflict and resubmit the request.
I think it should be 409 because the conflict can be resolved by re-issuing the request with different email address.
HTTP status codes are not meant to "invented".
409 CONFLICT sounds OK to me. Including details in the body ist OK, too, if your client needs to know.
Don't use 409. Use 403.
[409] is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request.
It's for a request that should have been OK, but has a problem that can be resolved. If you edit a document and PUT the revised text but someone else did the same thing before you did, you should have a chance to look at the other person's work so you don't accidentally undo all their work. You'd get a 409 which means, if you want to revise it, you should send your revision with an indication that you've seen the latest revision by the other person -- i.e. you know what you're doing.
There's no way to 'correct' a redundant attempt to register. The only way to avoid the conflict is to register with a different username, but that's very incorrect.
I'm imagining a POST request that takes a username and email address and creates a new resource dedicated to that new user (which should now be used for validation), sending that resource's URL in an email. So you're dealing with the refusal of the POST request handler to create a new resource, for a reason specific to the business model of your application (rather than an HTTP-related reason like bad syntax).
There's no status code more specific to what you want than 403. In this case, all you should use HTTP's vocabulary to communicate is 'that's not allowed' -- use the layer on top of HTTP to communicate why, like a polite HTML page or a JSON object for the client to understand and render as a polite HTML page.
409 should be ok; for the details https://datatracker.ietf.org/doc/html/draft-nottingham-http-problem-04 might be of interest.
The background is like this:
The client web browser send a request to the server;
The server program will launch some biz check rules before doing the real work.
If check fail, some tips should be feed back to the client browser.
So, here is the question. Should I use an error response http code to indicate this, or use 200 directly, and then parse the message from response body.
Sometimes, this is not a problem. But, some client component give some util methods if error code returned. So, that's a hard decision to make:
return 200,and error message. parse and show them myself;
return some code like 500, let the client component to show it directly.
I would suggest to use as many http status codes as possible. That is a standard and why should you not use them?
Here are some examples where IMHO the usage of http status codes makes sense:
Somebody wants a dataset wich is not aviable use 404 not found
A secured ressource needs an authentification use 401
A ressource which is not aviable for the currient user should get a 403 forbidden
A error accours which you cannot handle well write out an 500 status
And so on
Look also for the logic for REST-APIs there you can see the advantages.
Typically, you'll want to indicate the reason the service failed. Returning custom errors can also potentially allow the client application to respond in an appropriate way. If an input validation check fails, for instance, I imagine the user would appreciate the chance to fix and resubmit the request. An HTTP error won't be enough to indicate what exactly went wrong.
What HTTP status code should I return when a POST request is made to my RESTful API but the content in the POST field (let's say an XML) is invalid?
I would like to build a proper RESTful web service so I want to know.
I am now returning 405 when a HTTP method not supported by specific API is used, 200 when everything goes ok and 500 for all other errors (XML validation error etc).
Thank you.
I would respond with 400
400 Bad Request
The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.
That's what status code 422 is for.
I'm developing a RESTful application that integrates with other webservices.
My question is, which HTTP status should I return if my client posts data that is invalid for one of those webservices? For example, if it posts a name that is invalid for a webservice that my application uses, which of the 4** status codes should I return, considering it's a user input error?
Some considerations I've made, and why I'm not comfortable of using them:
400: The data is invalid, but not the request format itself
403: The server is not refusing to respond, although the data is invalid
406: The error is in a provided parameter, not in the "accept" header
412: The error has nothing to do with "If-Match" header
So, what would you use in this case?
Stick with 400, or have a look at 422 (which may be close to what you need).
In real life, HTTP status codes for REST and other web services can be vague and hard to clearly specify. Things also get interesting if your client is actually talking to a proxy server and that proxy sends back its own status. If there's a problem in your web service (perhaps below your app) you may just get 500.
In the past I would opt for returning 200 and using your own JSON-or-whatever structure for returning error information for your client.