[Developers] Freebase API Error response format

[Tim Kientzle]

The preferred method is to check code.startswith("/api/status/ok").   
Code values all begin with "/api/status/error" or "/api/status/ok"  
depending on the success or failure.  These path-like values are  
typically extended with additional information depending on the  
detailed status.

The code values are used in three places with three slightly different  
meanings:

1) Outer envelope.  There's always a code value here indicating  
overall success or failure.

2) Sub-response.  API entry points that accept multiple sub-requests  
(such as mqlread and mqlwrite) will have code values attached to each  
sub-response, since each sub-request can succeed or fail independently.

3) Messages.  Each returned message has a human-readable string (in  
English) and a detailed code value.  Our intention is for the detailed  
code values to be useful in looking up translated error messages.

We're also discussing creating topics in Freebase with the same names  
as the code values in order to document details of the various errors  
and possibly even provide translated text, but that's still a little  
ways out.

TBKK


On Mar 28, 2008, at 1:33 PM, David Flanagan wrote:

> While on this topic, what is the officially sanctioned best way to  
> test
> for success of a query?
>
> 	David Flanagan
>
> Aseem Mohanty wrote:
>> Hi All.
>>
>> There is an ongoing internal effort to standardize the error response
>> format for all API service calls. Since the changes are mainly  
>> additive
>> in nature, for the most part this should not effect, and more
>> importantly break, any existing applications that parse the error
>> response from Freebase services. This change is in the pipeline is  
>> not
>> currently deployed on www.freebase.com or sandbox.freebase.com
>>
>> I have outlined the changes below. If it turns out that your  
>> application
>> may break because of the changes please let me know and we can try  
>> and
>> resolve any issues your application might have.
>>
>> Error Response Format:
>> FIXED - indicates that the field will be there
>> OPT   - indicates that the field may or may not be there
>>
>> NOTE: This is a contrived example and should not be considered as a  
>> real
>> error response.
>>
>> {
>>    # the HTTP status code for the request, since some services  
>> (notably
>>    # MQL may return an HTTP 200 for partial error conditions
>>    # - FIXED -
>>    "status": "400 Bad Request",
>>
>>    # Service level code or module to indicate which service failed
>>    # - FIXED -
>>    "code": "/api/status/error/trans",
>>
>>    # Detailed information about what the nature of the error is
>>    # - FIXED -
>>    "messages": [{
>>
>>      # Application level machine-readable error descriptor
>>      #  - FIXED -
>>      "code": "/api/status/error/image_thumb/image_too_large",
>>
>>      # Application level human-readable error description
>>      # - FIXED -
>>      "message": "The original image is larger than 16 MP and cannot  
>> be
>> thumbnailed."
>>
>>      # Additional fields that might help in identifying the source of
>>      # the error. All remaining fields are optional
>>      # - OPT -
>>      "id": "/guid/9202.....1234",
>>      "dim": "7000x7000"
>>      ....
>>    }]
>>  }
>>
>> Thanks.
>> Aseem Mohanty
>> _______________________________________________
>> Developers mailing list
>> Developers at freebase.com
>> http://lists.freebase.com/mailman/listinfo/developers
>>
>
> _______________________________________________
> Developers mailing list
> Developers at freebase.com
> http://lists.freebase.com/mailman/listinfo/developers