Best Practices: handling 404 responses

Endpoints will return 404's, sometimes immediately after trying to retrieve (GET) the object after receiving a webhook for object.created, this document aims to explain this behaviour.

If you receive a 404 you should consider the item deleted, typically this makes up 1% of all http_responses.


Endpoint /messages & /threads: 

Scenario / Cause

  • Offset: When no more objects can be located, i.e. end of an offset / limit we return a 404 
  • Draft: Create /draft then /send the message_id changes.
    • Resulting in two webhooks for the same message, one returns a 404.
  • Consolidate: Message sent then receive a message.created webhook which returns 404:
    • This can happen as the messages are consolidated or providers change the ID, especially common with IMAP.
  • Provider: Message is permanently deleted on the provider
    • Next time you try to retrieve it you receive a 404 - there is no message.deleted webhook.
  • RAW message/rfc822: GET /messages with message/rfc822 (RAW) returns 404, but without message/rfc822, it returns 200
    • The email is likely in a deletions folder. Provider doesn't return the raw content of messages in the deletions folder. It is also possible that the message does not exist on the provider, then it will be shortly deleted on Nylas also.

Endpoint /files:

Endpoint /events:

  • Provider: GET /events immediately after event.created results in 404, no correlating POST in API logs.
    • Event created by the provider, Nylas synced then the provider promptly permanently deleted.
    • These events are not created by the User via the provider, as deleted events by the user simply change the status == cancelled 
    • We do not track what these events are, however addons / browser plugins to mail clients such a Time-management software an cause this behaviour.





Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request



Please sign in to leave a comment.