JsonDerulo-API-Spec/errors.md

Errors

back to index

Error Response Format

All error responses follow the same shape:

{
    "message":"Session expired or invalid [request_id: 12346480868868238719]","success":false
}

The request_id is always included at the end of the error message so you can look it up in the server logs aswell as being included in the message part so it is displayed to users/clients. The length of the request_id is capped at 32 Numbers and shouldnt be shorter than like 8)

Some endpoints might include extra fields (like endpoint for toolkit errors or results for batch query errors) but success and error are always there.

Status Codes

The following status codes (and what they mean) should be returned by JsonDerulo API compliant server

Code	When
200	everything worked and Json Derulo is happy
400	bad request, missing fields, invalid table or column names, too many WHERE conditions, etc.
401	no token provided, token invalid or expired
403	you dont have permission (power level too low, IP not whitelisted, table access denied)
404	toolkit not found or disabled, endpoint path doesnt exist
429	rate limited, wait and try again
500	server error, database query failed, config reload failed, json derulo died
502	toolkit endpoint got an error from upstream (HTTP proxy mode)
503	database is down, depressed or having a stroke

Notes

• difference between 401 and 403: you get 401 when theres no valid session at all and you are trying to betray the jsonderulo server. 403 is when you have a session but your power (bottom) level or json's permissions dont allow the action.
• 503 only happens when the server has detected database connectivity loss. Server shouldnt crash, but tells you the database is currently having a hissifit and will keep trying to reconnect and pass your request in the background.
• batch query errors should be able to return partial results with a results array showing which sub queries succeeded and which failed.