Why?

PRs #405 and #406 documented two new endpoints in the Unstable spec but introduced several discrepancies between the spec and actual backend behavior. An audit identified 5 issues — wrong error formats, missing enums, incorrect error codes, and undocumented auth requirements.

How?

Five targeted fixes to descriptions/0/api.intercom.io.yaml, each verified against backend source code.

Decisions

Kept all fixes in a single PR since they're all corrections to the same spec file from the same audit pass.

Backend evidence for each fix

Fix 1: 400 error format on GET /messages/whatsapp/status

Was: flat {type: error, request_id, message} — Should be: {type: "error.list", errors: [{code, message}]}

Backend proof: All ApiCodedError exceptions go through error_handler.rb → render_error → render_errors, which always wraps in the error.list format. The 404 example in the same endpoint already used the correct format — this was an inconsistency within the same PR.

Fix 2: type enum missing on whatsapp_message_status

Was: no enum, just example: broadcast_outbound — Should be: 5 values

Backend proof: whatsapp_event.rb:14-19 defines the enum:

enum :type, {
  broadcast_outbound: 'broadcast_outbound',
  inbox_outbound: 'inbox_outbound',
  inbound: 'inbound',
  admin_reply: 'admin_reply',
  admin_reply_with_template: 'admin_reply_with_template',
}

Fix 3: required properties on whatsapp_message_status

Was: no required array — Should be: [conversation_id, status, type, message_id]

Backend proof: messages_controller.rb whatsapp_status action always builds the response hash with conversation_id, status, type, and message_id from non-nullable DB columns.

Fix 4: 401 error code on PUT conversation_parts

Was: code: unauthorized, message: Access Token Invalid — Should be: code: token_unauthorized, message: Not authorized to access resource

Backend proof: code.rb:44 defines TOKEN_UNAUTHORIZED = 'token_unauthorized'. The controller's unauthorized_api_error method returns message: 'Not authorized to access resource'.

Fix 5: WRITE_TICKETS scope undocumented on PUT conversation_parts

Was: no mention of ticket scope — Should be: documented

Backend proof: conversation_parts_controller.rb:58-61 checks unauthorized_ticket_write? which verifies @token.scope.include?(WRITE_TICKETS) for ticket conversations.

_{Generated with Claude Code}