Internet DRAFT - draft-foster-mgcp-returncodes

draft-foster-mgcp-returncodes




Internet Engineering Task Force                           B. Foster 
Internet Draft                                       C. Sivachelvan 
Document: <draft-foster-mgcp-returncodes-03.txt>      Cisco Systems 
Category: Informational                                 August 2003 
                                                        
 
        Media Gateway Control Protocol (MGCP) Return Code Usage 
 
Status of this Document 
 
  This document is an Internet-Draft and is in full conformance with 
  all provisions of Section 10 of RFC2026 
   
  Internet-Drafts are working documents of the Internet Engineering 
  Task Force (IETF), its areas, and its working groups. Note that other 
  groups may also distribute working documents as Internet-Drafts. 
   
  Internet-Drafts are draft documents valid for a maximum of six months 
  and may be updated, replaced, or obsoleted by other documents at any 
  time. It is inappropriate to use Internet-Drafts as reference 
  material or to cite them other than as "work in progress." 
   
  The list of current Internet-Drafts can be accessed at 
  http://www.ietf.org/ietf/1id-abstracts.txt 
   
  The list of Internet-Draft Shadow Directories can be accessed at 
  http://www.ietf.org/shadow.html. 
   
   
 
Abstract 
 
  This document provides implementation guidelines for the use of 
  return codes in the Media Gateway Control Protocol MGCP 1.0 (RFC 
  3435). 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. 
 
   












 
Foster & Sivachelvan         Informational                     [Page 1] 

                        MGCP Return Code Usage              August 2003 

                            Table of Contents 
1.0. Introduction.....................................................2 
 1.2. Document Organization...........................................2 
2.0. Return Code Usage................................................3 
 2.1. Return Code Categories..........................................3 
 2.2. Return Code Situations and Categories...........................4 
 2.3. Summary of Return Code Categories..............................18 
3.0. Additional Guidelines...........................................19 
 3.1. Gateway Recommendations........................................19 
 3.2. Call Agent Recommendations.....................................19 
4.0. Security Considerations.........................................20 
5.0. Acknowledgements................................................20 
6.0. References......................................................20 
7.0. Authors' Addresses..............................................20 
8.0. Full Copyright Statement........................................21 
Acknowledgement......................................................21 
   
   
   
   
   
1.0. 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. 
   
 
 
 

 
Foster & Sivachelvan         Informational                     [Page 2] 

                        MGCP Return Code Usage              August 2003 

2.0. 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.  
   
  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.), 
 
Foster & Sivachelvan         Informational                     [Page 3] 

                        MGCP Return Code Usage              August 2003 

  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. 
   
  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. 
        





 
Foster & Sivachelvan         Informational                     [Page 4] 

                        MGCP Return Code Usage              August 2003 

  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 
       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 
 
Foster & Sivachelvan         Informational                     [Page 5] 

                        MGCP Return Code Usage              August 2003 

       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 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 
       codec requiring lower bandwidth codec and have a successful 
       result. Alternatively it could treat this as a "Temporary 
       Failure" for this codec. 
        

 
Foster & Sivachelvan         Informational                     [Page 6] 

                        MGCP Return Code Usage              August 2003 

       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, 
       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 
 
Foster & Sivachelvan         Informational                     [Page 7] 

                        MGCP Return Code Usage              August 2003 

       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. 
        
       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". 
        


 
Foster & Sivachelvan         Informational                     [Page 8] 

                        MGCP Return Code Usage              August 2003 

  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). 
        
  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". 
        


 
Foster & Sivachelvan         Informational                     [Page 9] 

                        MGCP Return Code Usage              August 2003 

  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. 
        
       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".  
 
Foster & Sivachelvan         Informational                    [Page 10] 

                        MGCP Return Code Usage              August 2003 

        
  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, 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". 
 
Foster & Sivachelvan         Informational                    [Page 11] 

                        MGCP Return Code Usage              August 2003 

        
  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". 
        
  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. 
 
Foster & Sivachelvan         Informational                    [Page 12] 

                        MGCP Return Code Usage              August 2003 

        
       Category:    "State Mismatch". The Call Agent needs to send down 
       a digit map in order to continue with the call. 
        
  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).  
        
       Category:    "Provisioning Mismatch". 
 
Foster & Sivachelvan         Informational                    [Page 13] 

                        MGCP Return Code Usage              August 2003 

        
  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. 
        
       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.   
        
 
Foster & Sivachelvan         Informational                    [Page 14] 

                        MGCP Return Code Usage              August 2003 

       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). 
        
  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". 
        
   
   
 
Foster & Sivachelvan         Informational                    [Page 15] 

                        MGCP Return Code Usage              August 2003 

  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. 
        
  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 
 
Foster & Sivachelvan         Informational                    [Page 16] 

                        MGCP Return Code Usage              August 2003 

       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". 
        
  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. 
 
Foster & Sivachelvan         Informational                    [Page 17] 

                        MGCP Return Code Usage              August 2003 

        
       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. 
   
   ------------------------------------------------------------------ 
  |  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. 
   


 
Foster & Sivachelvan         Informational                    [Page 18] 

                        MGCP Return Code Usage              August 2003 

     * 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). 
   
3.0. 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]. 
     * For categories "Service Failure", "Provisioning Mismatch", 
       "Temporary Failure", and "Remote Connection Descriptor Error", 
 
Foster & Sivachelvan         Informational                    [Page 19] 

                        MGCP Return Code Usage              August 2003 

       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, 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.0. 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.0. Acknowledgements 
   
  Thanks also to Kevin Miller, Joe Stone, Flemming Andreasen, Bob 
  Biskner for input contributions used in this document. 
   
6.0. References 
   
  [1] Andreasen and Foster, Media Gateway Control Protocol (MGCP) 
      Version 1.0, RFC 3435, January 2003 
  [2] Foster and Andreasen, Basic MGCP Packages, [editors note: to be 
      provided with RFC number when available for draft-foster-mgcp-
      basic-packages-10.txt]. 
  [3] Handley, M. and V. Jacobson, SDP: Session Description Protocol, 
      RFC 2327, April 1998. 
 
7.0. Authors' Addresses 
 
  C. Sivachelvan 
  Cisco Systems 
  2200 East President George Bush Turnpike 
  Richardson, TX, 75082 
  chelliah@cisco.com 
   
  B. Foster 
  Cisco Systems 
  bfoster@cisco.com





 
Foster & Sivachelvan         Informational                    [Page 20] 

                        MGCP Return Code Usage              August 2003 

   
8.0. 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 assigns. 
   
  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 21]