doc: Add RFC documents

1 files changed, 1347 insertions, 0 deletions

diff --git a/doc/rfc/rfc3661.txt b/doc/rfc/rfc3661.txt
new file mode 100644
index 0000000..082a6c2
--- /dev/null
+++ b/doc/rfc/rfc3661.txt
@@ -0,0 +1,1347 @@
+
+
+
+
+
+
+Network Working Group                                          B. Foster
+Request for Comments: 3661                                C. Sivachelvan
+Updates: 3435                                              Cisco Systems
+Category: Informational                                    December 2003
+
+
+        Media Gateway Control Protocol (MGCP) Return Code Usage
+
+Status of this Memo
+
+   This memo provides information for the Internet community.  It does
+   not specify an Internet standard of any kind.  Distribution of this
+   memo is unlimited.
+
+Copyright Notice
+
+   Copyright (C) The Internet Society (2003).  All Rights Reserved.
+
+Abstract
+
+   This document provides implementation guidelines for the use of
+   return codes in RFC 3435, Media Gateway Control Protocol (MGCP)
+   Version 1.0.  Return codes in RFC 3435 do not cover all possible
+   specific situations that may ever occur in a gateway.  That is not
+   possible and not necessary.  What is important is to ensure that the
+   Call Agent that receives a return code behaves appropriately and
+   consistently for the given situation.  The purpose of this document
+   is to provide implementation guidelines to ensure that consistency.
+
+Table of Contents
+
+   1.  Introduction. . . . . . . . . . . . . . . . . . . . . . . . .   2
+       1.2.  Document Organization . . . . . . . . . . . . . . . . .   2
+   2.  Return Code Usage . . . . . . . . . . . . . . . . . . . . . .   2
+       2.1.  Return Code Categories. . . . . . . . . . . . . . . . .   2
+       2.2.  Return Code Situations and Categories . . . . . . . . .   3
+       2.3.  Summary of Return Code Categories . . . . . . . . . . .  19
+   3.  Additional Guidelines . . . . . . . . . . . . . . . . . . . .  21
+       3.1.  Gateway Recommendations . . . . . . . . . . . . . . . .  21
+       3.2.  Call Agent Recommendations. . . . . . . . . . . . . . .  21
+   4.  Security Considerations . . . . . . . . . . . . . . . . . . .  22
+   5.  Acknowledgements. . . . . . . . . . . . . . . . . . . . . . .  22
+   6.  Normative References. . . . . . . . . . . . . . . . . . . . .  22
+   7.  Authors' Addresses. . . . . . . . . . . . . . . . . . . . . .  23
+   8.  Full Copyright Statement. . . . . . . . . . . . . . . . . . .  24
+
+
+
+
+
+
+Foster & Sivachelvan         Informational                      [Page 1]
+
+RFC 3661                 MGCP Return Code Usage            December 2003
+
+
+1.  Introduction
+
+   This document provides implementation guidelines for the use of
+   return codes in the Media Gateway Control Protocol MGCP 1.0 [1].
+   Return codes in [1] do not cover all possible specific situations
+   that may ever occur in the gateway.  That is not possible and not
+   necessary.  What is important is to ensure that the Call Agent that
+   receives that return code behaves appropriately and consistently for
+   the situation that occurred.  The solution described in this document
+   is to categorize return codes that gateways return based on the
+   expected behavior for the Call Agents that receive them.
+
+   Categorizing errors helps both Call Agent and gateway developers: it
+   helps gateway developers choose an appropriate return code when a
+   specific one for the situation is not available; it also helps Call
+   Agent developers ensure that there is consistent behavior for the
+   return code that is received.
+
+1.2.  Document Organization
+
+   In addition to categorizing return codes (section 2.1), section 2.2
+   provides a consolidated list of return codes in terms of "situations"
+   that may have triggered and the "categories" that they fall under.
+   This provides some additional implementation guidelines for the use
+   of these return codes.  Section 2.3 includes a summary of the return
+   codes and their categories.  Section 3 provides some additional
+   implementation guidelines for Call Agent and gateway developers.
+
+2.  Return Code Usage
+
+2.1.  Return Code Categories
+
+   The following categorizes return codes from gateways based on
+   expected Call Agent behavior.
+
+   Category normal: These return codes are used in normal operation and
+      do not represent error conditions.
+
+   Category none (specific errors requiring specific action): A return
+      code associated with a specific situation in the gateway that will
+      invoke a corresponding specific Call Agent behavior.  As such,
+      these return codes are not categorized into a common behavioral
+      category.
+
+   Category "Service Failure": A category in which the endpoint is
+      either out-of-service or the treatment by the Call Agent is
+      expected to be the same as for an out-of-service endpoint.
+
+
+
+
+Foster & Sivachelvan         Informational                      [Page 2]
+
+RFC 3661                 MGCP Return Code Usage            December 2003
+
+
+   Category "Provisioning Mismatch": A situation where the gateway has
+      indicated that it does not support what the Call Agent has asked
+      it to do.  This may be caused by a lack of synchronization between
+      the provisioning of the Call Agent and the gateway.  Note that
+      attempts should be made to weed out these types of error
+      situations during integration testing.
+
+   Category "Temporary Failure": The transient nature of this error is
+      such that this particular call is likely to be permanently
+      affected but later calls on the same endpoint may proceed
+      successfully.  Typically the situation that caused this error is
+      not going to disappear unless there is some change in state in the
+      gateway or network (e.g., more bandwidth becomes available, more
+      CPU resources become available etc.).  This situation is not
+      likely to change in a few 10's of milliseconds but could change
+      within some number of seconds or minutes later (as resources
+      become free), i.e., within the time period that you might expect a
+      different call to be tried on that endpoint.
+
+   Category "State Mismatch":  A case where there is a state mismatch
+      between the Call Agent and the gateway that can be resolved by the
+      Call Agent making a request that is more appropriate to the
+      gateway state.  Although categorized with a common category
+      indicator the behavior of the Call Agent will depend on the
+      situation (the type of state mismatch that has occurred as well as
+      other state information, e.g., call state).
+
+   Category "Remote Connection Descriptor Error": This indicates some
+      mismatch between the two gateways involved in the call.  Note that
+      per RFC 2327, all gateways should ignore SDP attributes that they
+      do not recognize (i.e., lack of recognition of an SDP attribute
+      should not be the cause of an error indication).
+
+   The exact behavior of the Call Agent for the above categories may
+   depend on the type of endpoint (analog, ISUP trunk, CAS trunk, etc.),
+   whether this is the originating or terminating endpoint in the call
+   and possibly other information related to call state.  This document
+   does not attempt to outline the Call Agent behavior based on call
+   state.  Instead, it just recommends that the Call Agent behavior be
+   consistent based on a combination of call state and the specific
+   category of error received.
+
+2.2.  Return Code Situations and Categories
+
+   This section describes return codes in MGCP 1.0 [1] in terms of
+   "situations" that may have triggered that return code and
+   "categories" to which the return code belongs.  The purpose is to
+   provide developers additional guidelines for return code use.
+
+
+
+Foster & Sivachelvan         Informational                      [Page 3]
+
+RFC 3661                 MGCP Return Code Usage            December 2003
+
+
+   Note that any indication that a response is valid for a
+   NotificationRequest (RQNT) is also an indication that it is valid for
+   a connection handling request, i.e., CreateConnection (CRCX),
+   ModifyConnection (MDCX), or DeleteConnection (DLCX) with an
+   encapsulated RQNT.  The same holds for the EndpointConfiguration
+   (EPCF) command.
+
+   000 - Response acknowledgement
+
+        Response valid for:    Confirmation of a final response after a
+        provisional response (3-way handshake).
+
+        Situation:   If the final response that follows a provisional
+        response contains an empty response acknowledgement parameter, a
+        Response Acknowledgement is used to acknowledge the final
+        response (section 3.5.6 of [1]).
+
+        Category:    normal.
+
+   100 - Transaction in progress
+
+        Response valid for:    Any command that may result in a long
+        transaction execution time, e.g., more than 200 ms.
+
+        Situation:   When a transaction is expected to take a processing
+        time that is beyond the normal retry timer, the gateway will
+        return a provisional response.  A final response will be
+        provided later, after the transaction has completed.  Refer to
+        section 3.5.6 of [1].  An example of this might be a
+        CreateConnection command using RSVP, where the time to create
+        the connection may be longer than usual because of the need to
+        perform the network resource reservation.
+
+        Category:    normal.
+
+   101 - Transaction has been queued for execution
+
+        Response valid for:    Any command.
+
+        Situation:   As described in [1], Section 4.4.8, we assume that
+        Call Agents and gateways conceptually maintain a queue of
+        incoming transactions to be executed.  Associated with this
+        transaction queue is a high-water and a low-water mark.  Once
+        the queue length reaches the high-water mark, the entity should
+        start issuing 101 provisional responses (transaction queued)
+        until the queue length drops to the low-water mark.  This
+        applies to new transactions as well as to retransmissions.  A
+
+
+
+
+Foster & Sivachelvan         Informational                      [Page 4]
+
+RFC 3661                 MGCP Return Code Usage            December 2003
+
+
+        final response will be provided later, after the transaction has
+        completed.  In this case, the Call Agent should throttle back
+        its request rate for this gateway.
+
+        Category:    normal.
+
+   200 - Transaction executed normally
+
+        Response valid for:    Any command (including DeleteConnection).
+
+        Situation:   Normal response as a result of successful
+        execution.  The 250 response code can be used to acknowledge a
+        successful completion of a DeleteConnection command.  However, a
+        200 response code is also appropriate.
+
+        Category:    normal
+
+   250 - The connection was deleted
+
+        Response valid for:    DeleteConnection.
+
+        Situation:   Response to a successful DeleteConnection command.
+
+        Category:   normal
+
+   400 - Unspecified transient error
+
+        Response valid for:    Any command.
+
+        Situation:   Unspecified transient error.  A more specific error
+        code should be used if one is available since this error code
+        provides very little information.  If used, some specific
+        commentary should be included to aid in debug.
+
+        Category:    "Temporary Failure".
+
+   401 - The phone is already off-hook
+
+        Response valid for:    NotificationRequest.
+
+        Situation:   This is returned in response to a request for an
+        off-hook transition requested event when the phone is already
+        off-hook.  It is also returned when a request is made to
+        generate a signal that has an explicit on-hook precondition in
+        the signal definition, such as the ringing signal ("rg") in the
+        Line package [2].  It is also returned when requesting an
+
+
+
+
+
+Foster & Sivachelvan         Informational                      [Page 5]
+
+RFC 3661                 MGCP Return Code Usage            December 2003
+
+
+        incoming off-hook/seizure indication for a Channel Associated
+        Signaling (CAS) trunk when the incoming hook-state for that
+        trunk is already off-hook.
+
+        Category: "State Mismatch".  If the Call Agent makes the request
+        with a requested event indicating a different hook-state, the
+        request should not result in this return code again.
+
+   402 - The phone is already on-hook
+
+        Response valid for:    NotificationRequest.
+
+        Situation: This is returned in response to a request for an on-
+        hook or hook-flash requested event when the phone is already
+        on-hook.  It is also returned when a request is made to generate
+        a signal that has an explicit off-hook precondition in the
+        signal definition, such as the dial tone ("dl") in the Line
+        package [2].  It is also returned when requesting an incoming
+        on-hook indication for a CAS trunk when the incoming hook-state
+        for that trunk is already on-hook.
+
+        Category:    "State Mismatch".  If the Call Agent makes the
+        request with a requested event indicating a different hook-
+        state, the request should not result in this error again.
+
+   403 - Insufficient resources available at this time
+
+        Response valid for:    Any command.
+
+        Situation:   This is returned if the request cannot be processed
+        due to a temporary lack of gateway resources, such as CPU
+        utilization, DSP resources, memory etc; however, the command may
+        succeed at a later time when resources free up.  Note that lack
+        of network resources should not result in this code (i.e.,
+        return code 404 would be more appropriate).
+
+        Category:    "Temporary Failure".
+
+   404 - Insufficient bandwidth at this time.
+
+        Response valid for:    CreateConnection, ModifyConnection.
+
+        Situation:   This is an indication that there is not enough
+        bandwidth available to sustain the call.  It is as a result of
+        some failed bandwidth check (could be RSVP or some other
+        mechanism).  It is possible that the Call Agent could request a
+
+
+
+
+
+Foster & Sivachelvan         Informational                      [Page 6]
+
+RFC 3661                 MGCP Return Code Usage            December 2003
+
+
+        codec requiring lower bandwidth codec and have a successful
+        result.  Alternatively, it could treat this as a "Temporary
+        Failure" for this codec.
+
+        Category:    "Temporary Failure".  Although categorized under
+        this general category, note that the Call Agent could apply some
+        specific behavior (try a lower bandwidth codec) depending on
+        policy.
+
+   405 - Endpoint is restarting
+
+        Response valid for:    Any command.
+
+        Situation:   It may be returned to requests made when the
+        endpoint is in-service and has initiated the restart procedures
+        (see [1], Section 4.4.6) but the procedure has not yet
+        completed.  If the request is made at a later time, it may be
+        "successful" but may not be appropriate (because of possible
+        state mismatch).  The Call Agent should proceed after it
+        believes the restart procedure has completed.
+
+        Category:    "Temporary Failure"
+
+   406 - Transaction Timeout
+
+        Response valid for:    Any command.
+
+        Situation:   The transaction took longer than expected and has
+        been aborted.  An example might be a transaction where a
+        provisional response (100 response code) was returned.
+        Following that, the gateway determined that the actual
+        transaction was taking longer than should reasonably be expected
+        and as a result it aborted the transaction and returned 406 as
+        the final response.
+
+        Category:    "Temporary Failure".  If this error code is
+        returned repeatedly, it could indicate a more serious problem.
+
+   407 - Transaction aborted by some external action.
+
+        Response valid for:    Any command.
+
+        Situation:   This is returned to indicate cancellation of a
+        pending request (see [1] Section 4.4.4).  For example,
+        DeleteConnection is received while processing a CreateConnection
+        or ModifyConnection.  Also, if either a ModifyConnection,
+
+
+
+
+
+Foster & Sivachelvan         Informational                      [Page 7]
+
+RFC 3661                 MGCP Return Code Usage            December 2003
+
+
+        NotificationRequest, or EndpointConfiguration command is in
+        progress, and the same command is received with a different
+        transaction Id, 407 will be returned.
+
+        Category: none (specific situation and behavior).
+
+   409 - Internal overload
+
+        Response valid for:    Any command.
+
+        Situation: Gateway is overloaded (e.g., too many requests per
+        second from the Call Agent) and is unable to process any more
+        transactions at this time. In this case, the Call Agent SHOULD
+        throttle back its request rate for this gateway as described in
+        [1], Section 4.4.8.
+
+        Category:    "Temporary Failure". Note that although the Call
+        Agent behavior with respect to the call being set up corresponds
+        to this general category, there is some specific Call Agent
+        behavior implied as well (i.e., the Call Agent throttling back).
+
+   410 - No endpoint available
+
+        Response valid for: CreateConnection using an "any of" wildcard.
+
+        Situation:   A CreateConnection request was made with an "any
+        of" ("$") wildcard and no endpoint was available to execute the
+        request. As described in [1], Section 2.3.5, when the "any of"
+        wildcard is used with the CreateConnection command, the endpoint
+        assigned MUST be in-service and MUST NOT already have any
+        connections on it.
+
+        Category: none (specific situation and behavior).
+
+   500 - Endpoint unknown
+
+        Response valid for:    Any command.
+
+        Situation:   There is no endpoint matching the EndpointId
+        provided with the command. This could be the result of a
+        provisioning mismatch between the Call Agent and the gateway or
+        it could be because a card was removed from the gateway so that
+        the endpoint is no longer available (in which case a
+        RestartInProgress should be received, although the Call Agent
+        cannot depend on this). Note that the endpoint is not just out-
+        of-service (in which case 501 would be used); it is completely
+        unknown/unavailable to the MGCP.
+
+
+
+
+Foster & Sivachelvan         Informational                      [Page 8]
+
+RFC 3661                 MGCP Return Code Usage            December 2003
+
+
+        Category:    "Provisioning Mismatch".
+
+   501 - Endpoint is not ready or is out of service
+
+        Response valid for:    Any command.
+
+        Situation:   This is returned if the endpoint is in a permanent
+        "not ready" state. This includes maintenance states such as
+        out-of-service. Note that an endpoint that has initiated the
+        restart procedure is in-service, and hence should not use this
+        return code, even if the restart procedure has not yet completed
+        (see [1], Section 4.4.5).
+
+        Category:    "Service Failure".
+
+   502 - Insufficient resources (permanent).
+
+        Response valid for:    Any command.
+
+        Situation:   This is returned when the endpoint does not have
+        sufficient resources and future requests on this endpoint are
+        expected to fail, meaning some resources dedicated to the
+        endpoint are broken (e.g., return code 529 - "hardware failure"
+        might be a more specific indication). For situations where
+        resources may become available in the future (i.e., resources
+        are pooled and not available at the present time), return code
+        403 should be used instead.
+
+        Category:    "Service Failure".
+
+   503 - "All of" wildcard too complicated.
+
+        Response valid for:    Any command.
+
+        Situation:   This is returned when the wildcard convention used
+        in the request is understood, but the requested command cannot
+        be processed with the specified wildcarding. An example of this
+        would be a NotificationRequest with a request such that a
+        failure would make it too difficult to roll back the state of
+        all the endpoints to what they were prior to the request.
+
+        Category: Normally treated as a "Provisioning Mismatch". Note
+        however, that the Call Agent could treat it differently by
+        recovering with some specific behavior (e.g., generate a number
+        of individual requests without wildcards instead of a single one
+        with the wildcard).
+
+
+
+
+
+Foster & Sivachelvan         Informational                      [Page 9]
+
+RFC 3661                 MGCP Return Code Usage            December 2003
+
+
+   504 - Unknown or unsupported command.
+
+        Response valid for:    Any unknown command.
+
+        Situation:   A command was requested other than those specified
+        in the MGCP specification [1], and the command is not supported.
+
+        Category:    "Provisioning Mismatch".
+
+   505 - Unsupported remote connection descriptor.
+
+        Response valid for: CreateConnection, ModifyConnection.
+
+        Situation:   One or more mandatory parameters or values in the
+        RemoteConnectionDescriptor are not supported by the gateway.
+        Note that, per [3], unsupported attribute lines must be ignored
+        and hence should not result in any errors.
+
+        Category:    "Remote Connection Descriptor Error".
+
+   506 - Inability to satisfy both local connection options and remote
+        connection descriptor simultaneously.
+
+        Response valid for: CreateConnection, ModifyConnection.
+
+        Situation:   The LocalConnectionOptions and
+        RemoteConnectionDescriptor contain one or more mandatory
+        parameters or values that conflict with each other and/or cannot
+        be supported at the same time (except for codec negotiation
+        failure - see error code 534).
+
+        Category:    "Remote Connection Descriptor Error".
+
+   507 - Unsupported Functionality.  Note that this error code SHOULD
+        only be used if there is no other more specific error code for
+        the unsupported functionality.
+
+        Response valid for:    Any command.
+
+        Situation:   Any situation where a request from the Call Agent
+        is not supported by the gateway - beyond the situations already
+        covered by other more specific return codes.
+
+        Category:    "Provisioning Mismatch".
+
+   508 - Unknown or unsupported quarantine handling.
+
+        Response valid for:    NotificationRequest.
+
+
+
+Foster & Sivachelvan         Informational                     [Page 10]
+
+RFC 3661                 MGCP Return Code Usage            December 2003
+
+
+        Situation:   The endpoint does not support or does not recognize
+        the requested quarantine handling.
+
+        Category:    "Provisioning Mismatch".
+
+   509 - Error in RemoteConnectionDescriptor
+
+        Response valid for: CreateConnection, ModifyConnection.
+
+        Situation: There is a syntax or semantic error in the Remote
+        Connection Descriptor.  For example, there is no IP address for
+        an RTP media stream.
+
+        Category: "Remote Connection Descriptor Error".
+
+   510 - Protocol error
+
+        Response valid for:    Any command.
+
+        Situation:   Some unspecified protocol error was detected.
+        Gateways should use this error as a last resort since it
+        provides very little information.  If used, some specific
+        commentary should be included to aid in debug.
+
+        Category:    "Provisioning Mismatch".
+
+   511 - Unrecognized parameter extension.
+
+        Response valid for:    Any command.
+
+        Situation:   It is returned if the requested command contains an
+        unrecognized mandatory parameter extension ("X+").  In MGCP 1.0,
+        this specifically refers to unrecognized parameters, since other
+        error codes are available for unrecognized connection modes
+        (517), unrecognized packages (518), unrecognized local
+        connection options (541), etc.
+
+        Category: "Provisioning Mismatch".
+
+   512 - Gateway not equipped to detect one of the requested events.
+
+        Response valid for:    NotificationRequest.
+
+        Situation:   A valid event was requested however the gateway is
+        not equipped to detect this event (i.e., the package is only
+        implemented partially).  Of course, such an implementation would
+        not conform to [1].  Note that if an invalid event was
+        requested, i.e., an event not defined in the relevant package,
+
+
+
+Foster & Sivachelvan         Informational                     [Page 11]
+
+RFC 3661                 MGCP Return Code Usage            December 2003
+
+
+        then error code 522 should be used.  Also note, that if the
+        package is unknown or unsupported, then error code 518 should be
+        used.
+
+        Category:    "Provisioning Mismatch".
+
+   513 - gateway is not equipped to generate one of the requested
+        signals.
+
+        Response valid for:    NotificationRequest.
+
+        Situation: A valid signal was requested, however the gateway is
+        not equipped to generate this signal (i.e., the package is only
+        implemented partially).  Of course, such an implementation would
+        not conform to [1].  Note that if an invalid signal was
+        requested, i.e., a signal not defined in the relevant package,
+        then error code 522 should be used.  Also note, that if the
+        package is unknown or unsupported, then error code 518 should be
+        used.
+
+        Category:    "Provisioning Mismatch".
+
+   514 - The gateway cannot send the specified announcement.
+
+        Response valid for:    NotificationRequest with a request for an
+        announcement to be played.
+
+        Situation:   This is a specific situation with respect to
+        playing announcements on an endpoint or connection associated
+        with the endpoint.  Error code 538 could be used instead.
+
+        Category:    "Provisioning Mismatch".
+
+   515 - Incorrect connection-id.
+
+        Response valid for:    CreateConnection, ModifyConnection,
+        DeleteConnection, NotificationRequest, AuditConnection.
+
+        Situation:   An unknown connection-id has been specified.  It is
+        possible that the connection has already been deleted.  It
+        should be noted that a connection-id can also supplied with
+        events and signals (e.g., "S: L/rt@connId").  Note that a
+        mismatch between connection-id and call-id should use error code
+        516.
+
+        Category:    "State Mismatch".
+
+
+
+
+
+Foster & Sivachelvan         Informational                     [Page 12]
+
+RFC 3661                 MGCP Return Code Usage            December 2003
+
+
+   516 - Unknown or incorrect call-id.
+
+        Response valid for: ModifyConnection, DeleteConnection.
+
+        Situation:   Unknown call-id, or the call-id supplied is
+        incorrect (e.g., connection-id not associated with this call-
+        id).
+
+        Category:    "State Mismatch".
+
+   517 - Invalid or unsupported mode.
+
+        Response valid for:    CreateConnection, ModifyConnection.
+
+        Situation:   This is returned if the command specifies a
+        connection mode that the endpoint does not support (note that
+        not all endpoints will support all modes).  Note that if the
+        unsupported mode is an extension connection mode, error code 518
+        (unsupported package) should be used instead.
+
+        Category:    "Provisioning Mismatch".
+
+   518 - Unsupported or unknown package.
+
+        Response valid for:    Any command
+
+        Situation:   A package name included in a request is not
+        supported (or unknown).  Note that the package name may be a
+        prefix to an event or other things (e.g., a parameter) as
+        defined in [1].  Note that it is recommended to include a
+        PackageList parameter with a list of supported packages in the
+        response.
+
+        Category:    "Provisioning Mismatch".
+
+   519 - Endpoint does not have a digit map.
+
+        Response valid for: NotificationRequest.
+
+        Situation:   Request was made to detect digits based on a digit
+        map and the gateway does not have a digit map.
+
+        Category:    "State Mismatch".  The Call Agent needs to send
+        down a digit map in order to continue with the call.
+
+
+
+
+
+
+
+Foster & Sivachelvan         Informational                     [Page 13]
+
+RFC 3661                 MGCP Return Code Usage            December 2003
+
+
+   520 - Endpoint is restarting.
+
+        Situation: This is normally a transient error in which error
+        code 405 SHOULD be used.  Gateways SHOULD not use this error
+        code unless there is some relevant situation that warrants the
+        category of "Service Failure".  Note that this was included in
+        [1] only to maintain backwards compatibility with previous
+        releases of the MGCP specification.
+
+        Category:    If it is returned, this return code will be treated
+        as category "Service Failure", i.e., as if this endpoint is
+        out-of-service.
+
+   521 - Endpoint re-directed to another Call Agent.
+
+        Response valid for: RestartInProgress.
+
+        Situation:   A RestartInProgress command was sent to the Call
+        Agent and the Call Agent returns this return code along with a
+        NotifiedEntity parameter pointing to another Call Agent.  The
+        gateway then sends a new RestartInProgress command to the Call
+        Agent specified in the Notified Entity.
+
+        Category:    none (specific situation and behavior).
+
+   522 - No such event or signal.
+
+        Response valid for:    NotificationRequest.
+
+        Situation:   This is returned if the requested event/signal name
+        is not registered with this package.  If on the other hand the
+        signal or event is part of the package but is not supported by
+        the gateway, then return code 512 or 513 SHOULD be provided
+        instead.  If the package is not supported, return code 518
+        SHOULD be returned.
+
+        Category:    "Provisioning Mismatch".
+
+   523 - Unknown action or illegal combination of actions.
+
+        Response valid for: NotificationRequest with one or more
+        requested events.
+
+        Situation:   Request was made with a requested event(s) that
+        included an action or actions defined in [1] that are either
+        unknown, unsupported or an illegal combination as indicated in
+        section 2.3.3 of [1].  Note that unsupported extension actions
+        should generate error code 518 (unsupported package).
+
+
+
+Foster & Sivachelvan         Informational                     [Page 14]
+
+RFC 3661                 MGCP Return Code Usage            December 2003
+
+
+        Category:    "Provisioning Mismatch".
+
+   524 - Internal inconsistency in Local Connection Options
+
+        Response valid for:    CreateConnection, ModifyConnection.
+
+        Situation:   This is returned if one or more of the
+        LocalConnectionOptions (LCO) parameters are coded with values
+        that are not consistent with each other (e.g., other LCO
+        parameters inconsistent with the network type).
+
+        Category:    "Provisioning Mismatch".
+
+   525 - Unknown extension in Local Connection Options.
+
+        Response valid for: CreateConnection, ModifyConnection.
+
+        Situation: This is returned if the request contains a Local
+        Connection Option with one or more unrecognized mandatory ("x+")
+        extensions.  Note that unsupported package extensions should use
+        error code 518 (unsupported package) instead.
+
+        Category: "Provisioning Mismatch".
+
+   526 - Insufficient bandwidth
+
+        Response valid for:    CreateConnection, ModifyConnection.
+
+        Situation:   In most cases where there is insufficient
+        bandwidth, a 404 return code should be used.  526 would be used
+        in cases where future requests are destined to fail.  An example
+        might be a very restricted bandwidth case, where there is not
+        enough bandwidth available for the codec requested even for a
+        single endpoint.  Making a request with the same codec in the
+        future will fail.  However, making a request for some other
+        codec (with a higher degree of compression) may pass.  For
+        cases, where the bandwidth is pooled over multiple endpoints and
+        could free up at some future time (because an endpoint becomes
+        inactive), then 404 is more appropriate.
+
+        Category:    If it is returned, this return code will be treated
+        as category "Provisioning Mismatch", e.g., the codec was
+        incorrectly provisioned for the bandwidth available.
+
+   527 - Missing RemoteConnectionDescriptor.
+
+        Response valid for: CreateConnection, ModifyConnection,
+        NotificationRequest.
+
+
+
+Foster & Sivachelvan         Informational                     [Page 15]
+
+RFC 3661                 MGCP Return Code Usage            December 2003
+
+
+        Situation: This is returned if the connection has not yet
+        received a RemoteConnectionDescriptor when one is required to
+        support the request.  This can for example happen if a
+        connection is attempted to be placed in "send/receive mode", or
+        if a signal is applied on a connection.
+
+        Category:    "Remote Connection Descriptor Error" in the case
+        where the other end did not provide a connection descriptor.
+        Alternatively, if this is an initial request made by a Call
+        Agent (such there is no remote connection descriptor), then this
+        is a "State Mismatch" problem.
+
+   528 -Incompatible protocol version
+
+        Response valid for:    Any command.
+
+        Situation:   A command was received with a protocol version that
+        was not supported.
+
+        Category:    "Provisioning Mismatch".  This could also be
+        treated as a "State Mismatch" problem if the there is a recovery
+        mechanism (e.g., Call Agent recognizes the protocol version
+        mismatch and switches to the correct protocol version)
+
+   529 - Internal Hardware Error.
+
+        Response valid for:    Any command.
+
+        Situation: A hardware fault occurred during the execution of a
+        command such that repeating this command will result in a
+        failure indication once again.  This is a slightly more specific
+        error code than error 502, although more commentary should be
+        provided (for debug purposes) if possible.
+
+        Category: "Service Failure".
+
+   530 - CAS Signaling Protocol Error.
+
+        Response valid for:    NotificationRequest.
+
+        Situation:   This is specific to Channel Associated Signaling
+        (CAS) interfaces.  A typical example might be an attempt to
+        outpulse digits failed for some reason.
+
+        Category:    none (specific situation and behavior).
+
+
+
+
+
+
+Foster & Sivachelvan         Informational                     [Page 16]
+
+RFC 3661                 MGCP Return Code Usage            December 2003
+
+
+   531 - Failure of a grouping of trunks (e.g., facility failure)
+
+        Response valid for:    CreateConnection, ModifyConnection,
+        NotificationRequest.
+
+        Situation:   Request made to an endpoint that has a failed trunk
+        connection (e.g., T1 or E1 failed).  Note that an RSIP should
+        have been sent as a result of the facility failure.  This is a
+        more specific response than return code 501.
+
+        Category:    "Service Failure".
+
+   532 - Unsupported value(s) in Local Connection Options.
+
+        Response valid for: CreateConnection, ModifyConnection.
+
+        Situation:   This is returned if one or more of the
+        LocalConnectionOptions parameters are coded with a value that
+        the gateway does not support.
+
+        Category:    "Provisioning Mismatch".
+
+   533 - Response too large
+
+        Response valid for:    Any command.
+
+        Situation: This would only be likely to occur in the case of an
+        audit where the maximum response packet size would end up being
+        too large.
+
+        Category:    none (specific situation and behavior).
+
+   534 - Codec negotiation failure
+
+        Response valid for: CreateConnection, ModifyConnection.
+
+        Situation:   The intersection between the list of codecs that
+        the gateway supports, the codecs allowed by the local connection
+        options and the codecs supplied in the Remote Connection
+        Descriptor (if provided) is empty.
+
+        Category:    "Provisioning Mismatch" if the error resulted from
+        an empty approved list of codes as described in [1], Section
+        2.6).  "Remote Connection Descriptor Error" if the error
+        resulted from an empty negotiated list of codecs, as described
+        in [1], Section 2.6.
+
+
+
+
+
+Foster & Sivachelvan         Informational                     [Page 17]
+
+RFC 3661                 MGCP Return Code Usage            December 2003
+
+
+   535 - Packetization period not supported
+
+        Response valid for:    CreateConnection, ModifyConnection.
+
+        Situation:   Normally this error should not be generated since
+        if the gateway is unable to support the packetization period
+        specified in the local connection options for the codec
+        indicated, it should follow the behavior specified in [1] (which
+        is to pick an appropriate value rather than failing the
+        request).
+
+        Category:    "none".
+
+   536 - Unknown or unsupported Restart Method
+
+        Response valid for: RestartInProgress.
+
+        Situation:   This error is generated by the Call Agent if it
+        receives a RestartInProgress command with an unsupported restart
+        method.  Note that if the restart method is an extension restart
+        method, error code 518 (unsupported package) should be used
+        instead.
+
+        Category:    "Provisioning Mismatch".
+
+   537 - Unknown or unsupported digit map extension
+
+        Response valid for: NotificationRequest.
+
+        Situation:   Digit map letter in the digit map unknown or
+        unsupported.  Note that this code does apply to extension digit
+        map letters as well.
+
+        Category:    "Provisioning Mismatch".
+
+   538 - Event/signal parameter error
+
+        Response valid for:    NotificationRequest.
+
+        Situation:   It is returned if the event/signal parameter is in
+        error or not supported.  If the event/signal or a package is not
+        supported, then one of 512, 513, 518, or 522 should be used
+        instead.
+
+        Category:    "Provisioning Mismatch".
+
+
+
+
+
+
+Foster & Sivachelvan         Informational                     [Page 18]
+
+RFC 3661                 MGCP Return Code Usage            December 2003
+
+
+   539 - Invalid or unsupported command parameter
+
+        Response valid for:    Any command.
+
+        Situation: This is returned if the command contains an invalid
+        or unsupported parameter, which is neither a package (which
+        would use return code 518) nor vendor specific extension (which
+        would use return code 511).  For example, if an endpoint does
+        not support the BearerInformation parameter of the
+        EndpointConfiguration command, this return code could be used.
+        Of course, such an implementation would not conform to [1].
+
+        Category:    "Provisioning Mismatch".
+
+   540 - Per endpoint connection limit exceeded
+
+        Response valid for: CreateConnection.
+
+        Situation:   A CreateConnection command was made, but the
+        gateway cannot support any additional connections on that
+        endpoint.
+
+        Category:    "State Mismatch".
+
+   541 - Invalid or unsupported Local Connection Options
+
+        Response valid for:    CreateConnection, ModifyConnection.
+
+        Situation:   This is returned if the command contains an invalid
+        or unsupported LocalConnectionOption, which is neither a package
+        (which would use return code 518) nor vendor specific extension
+        (which would use return code 511).
+
+        Category: "Provisioning Mismatch".
+
+2.3.  Summary of Return Code Categories
+
+   A summary of the categories of the various error codes is included in
+   the following table.  This information is also repeated in the
+   detailed error descriptions in the next section.
+
+
+
+
+
+
+
+
+
+
+
+Foster & Sivachelvan         Informational                     [Page 19]
+
+RFC 3661                 MGCP Return Code Usage            December 2003
+
+
+    ------------------------------------------------------------------
+   |  Category   | Return Codes                                       |
+   |-------------|----------------------------------------------------|
+   |   normal    | 000, 100, 101, 200, 250                            |
+   |-------------|----------------------------------------------------|
+   |    none     | 405, 407, 410, 510, 521, 530, 533, 535             |
+   |-------------|----------------------------------------------------|
+   | "Service    | 501, 502, 520, 529, 531                            |
+   |  Failure"   |                                                    |
+   |-------------|----------------------------------------------------|
+   |"Provisioning| 500, 503*, 504, 507, 508, 510, 511, 512, 513, 514, |
+   | Mismatch"   | 517, 518, 522, 523, 524, 525, 526, 528*, 532, 534*,|
+   |             | 536, 537, 538, 539, 541                            |
+   |-------------|----------------------------------------------------|
+   | "Temporary  | 400, 403, 404*, 405, 406, 409                      |
+   |  Failure"   |                                                    |
+   |-------------|----------------------------------------------------|
+   | "State      | 401, 402, 515, 516, 519, 540                       |
+   |  Mismatch"  |                                                    |
+   |-------------|----------------------------------------------------|
+   | "Remote     | 505, 506, 509, 527*                                |
+   |  Connection |                                                    |
+   |  Descriptor |                                                    |
+   |  Error"     |                                                    |
+    ------------------------------------------------------------------
+
+   Notes:
+
+   *  404: may be treated as a "Temporary Failure", but specific
+      behavior is possible (e.g., trying an alternate codec with lower
+      bandwidth requirement rather than failing this call).
+
+   *  503: rather than treating this as a "Provisioning Mismatch", it is
+      possible for the Call Agent to recover from this error.
+
+   *  527: See the detailed description for this error code in section
+      2.2. This could be treated as a "State Mismatch" depending on the
+      circumstances.
+
+   *  528: See the detailed description for this error code in section
+      2.2. This could be treated as a "State Mismatch" depending on the
+      circumstances.
+
+   *  534: See the note on error code 534 in the detailed description
+      section (2.2) of this document (may be treated as a "Remote
+      Connection Descriptor Error" if no local connection options were
+      supplied).
+
+
+
+
+Foster & Sivachelvan         Informational                     [Page 20]
+
+RFC 3661                 MGCP Return Code Usage            December 2003
+
+
+3.  Additional Guidelines
+
+   This section provides additional guidelines to Gateway and Call Agent
+   developers.
+
+3.1. Gateway Recommendations
+
+   The following guidelines are recommended for gateway implementations:
+
+   *  For uncategorized return codes (category "none") that involve
+      specific situations, gateways should make sure they do an accurate
+      mapping between the situation and the return code.
+
+   *  Also for category "State Mismatch", it is equally important that
+      the situation (and state) is accurately mapped to the specific
+      error code.
+
+   *  For situations similar to those involving return codes in "Service
+      Failure", Provisioning Mismatch", "Temporary Failure" and "Remote
+      Connection Descriptor Error" categories, the gateway should make
+      sure that it uses a return code in the correct category.
+
+   *  MGCP allows additional commentary to be included with the return
+      code. It is important that the gateway includes more specific
+      information concerning the situation for debug purposes.
+
+   *  It is recommended that return codes 502, 520 and 526 not be used
+      unless there is something that makes these permanent situations.
+      As indicated in the detailed description of these return codes,
+      403, 405 and 404 respectively are more appropriate in almost all
+      situations. If a gateway presently uses 502, 520 and 526 for
+      temporary situations and expects to upgrade to 403, 405 and 404,
+      the gateway should refrain from using 502, 520 and 526 for some
+      other use immediately after the upgrade. This is to avoid problems
+      where a Call Agent is expected to treat the same error code in two
+      different ways, e.g., 403 is a category "Temporary Failure" which
+      requires a different Call Agent behavior from 502 which is in
+      category "Service Failure".
+
+3.2.  Call Agent Recommendations
+
+   The following guidelines are recommended for gateway implementations:
+
+   *  Call Agents should handle return codes they do not recognize (or
+      do not expect) based on the first digit in the return code as
+      outlined in [1].
+
+
+
+
+
+Foster & Sivachelvan         Informational                     [Page 21]
+
+RFC 3661                 MGCP Return Code Usage            December 2003
+
+
+   *  For categories "Service Failure", "Provisioning Mismatch",
+      "Temporary Failure", and "Remote Connection Descriptor Error",
+      Call Agents are expected to treat return codes that are within the
+      same category in the same way (i.e., make the same decision, based
+      on the return code and other state information available to them).
+
+   *  Because there was little guidance given for return codes 502, 520
+      and 526 in RFC 2705 [4], Call Agents may have to treat these as
+      403, 405 and 404 respectively for gateways that have not been
+      updated according to [1] and these recommendations. The gateway
+      implementer should be consulted for information on the gateway
+      behavior for (now and in the future) for these return codes (i.e.,
+      it may be that return codes 502, 520 and 526 are presently used
+      incorrectly but will be replaced with 403, 405 and 404 in the
+      future).
+
+4.  Security Considerations
+
+   This document merely provides a convenient way to categorize MGCP
+   return codes in order to facilitate decisions related to failure
+   conditions; it does not impact MGCP security in any way.
+
+5.  Acknowledgements
+
+   Thanks also to Kevin Miller, Joe Stone, Flemming Andreasen, Bob
+   Biskner for input contributions used in this document.
+
+6.  Normative References
+
+   [1]  Andreasen, F. and B. Foster, "Media Gateway Control Protocol
+        (MGCP) Version 1.0", RFC 3435, January 2003.
+
+   [2]  Foster, B. and F. Andreasen, "Basic Media Gateway Control
+        Protocol (MGCP) Packages", RFC 3660, December 2003.
+
+   [3]  Handley, M. and V. Jacobson, "SDP: Session Description
+        Protocol", RFC 2327, April 1998.
+
+   [4]  Arango, M., Dugan, A., Elliott, I., Huitema, C. and S. Pickett,
+        "Media Gateway Control Protocol (MGCP) Version 1.0", RFC 2705,
+        October 1999.
+
+
+
+
+
+
+
+
+
+
+Foster & Sivachelvan         Informational                     [Page 22]
+
+RFC 3661                 MGCP Return Code Usage            December 2003
+
+
+7.  Authors' Addresses
+
+   C. Sivachelvan
+   Cisco Systems
+   2200 East President George Bush Turnpike
+   Richardson, TX, 75082
+
+   EMail: chelliah@cisco.com
+
+
+   B. Foster
+   Cisco Systems
+
+   EMail: bfoster@cisco.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Foster & Sivachelvan         Informational                     [Page 23]
+
+RFC 3661                 MGCP Return Code Usage            December 2003
+
+
+8.  Full Copyright Statement
+
+   Copyright (C) The Internet Society (2003).  All Rights Reserved.
+
+   This document and translations of it may be copied and furnished to
+   others, and derivative works that comment on or otherwise explain it
+   or assist in its implementation may be prepared, copied, published
+   and distributed, in whole or in part, without restriction of any
+   kind, provided that the above copyright notice and this paragraph are
+   included on all such copies and derivative works.  However, this
+   document itself may not be modified in any way, such as by removing
+   the copyright notice or references to the Internet Society or other
+   Internet organizations, except as needed for the purpose of
+   developing Internet standards in which case the procedures for
+   copyrights defined in the Internet Standards process must be
+   followed, or as required to translate it into languages other than
+   English.
+
+   The limited permissions granted above are perpetual and will not be
+   revoked by the Internet Society or its successors or assignees.
+
+   This document and the information contained herein is provided on an
+   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Acknowledgement
+
+   Funding for the RFC Editor function is currently provided by the
+   Internet Society.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Foster & Sivachelvan         Informational                     [Page 24]
+