How to specify error codes in Apiary Documentation?

Question

I want to specify the various exceptions/errors that have to be returned while making an API call. How do I achieve this with Apiary.

Waneta

Answer 1

Kyle's response is indeed correct. I will just add that if you want to add little bit more semantics to this you can write the other possible responses like this:

## POST /users/resendVerification/{userId}

Resends the user's verification code to the email address on record.

+ Response 201

+ Response 403

    Returned if the user does not have access to the requested account

    + Body

+ Response 404

    Returned if a user was not found for the given userId

    + Body

Note: The + Body is needed (even though it is empty) to distinguish the description from a message-body.

Streeto

Answer 2

I'm not aware of a specific syntax for error codes. In the past I've simply used bullet points. For example, this is my code for a re-request verification code API.

## POST /users/resendVerification/{userId}

Resends the user's verification code to the email address on record.</br>
• 403 is returned if the user does not have access to the requested account</br>
• 404 is returned if a user was not found for the given userId</br>

+ Response 201

Hope that helps.

Berkey

Ya this could be a solution. Actually I was looking for something where the error section would be highlighted for all the possible error codes. Any other API documentation tool you know about. Thanks for the answer. – Waneta

Mashery is another one. We evaluated them and Apiary and went with Apiary and have no complaints. Been great so far. – Berkey