Internet Engineering Task Force B. Foster Internet Draft C. Sivachelvan Document: <draft-foster-mgcp-returncodes-01.txt> Cisco Systems Category: Informational February 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 It is neither possible, nor necessary, to come up with an error code for all possible error situations that might occur. Consequently, some error codes in the MGCP Protocol (RFC 3435) are indications of very specific errors, whereas others are more generic in nature. In general, the choice of which error code to use in a given error situation may not always be clear. However, Call Agents may take very different action depending on which error code is being used. The objective is thus, to make sure that Call Agents behave the same for a given error situation that occurs in a Media Gateway. This document enables this by categorizing error codes based on expected Call Agent behavior. It also expands on the descriptions of the error codes in RFC 3435, giving additional guidelines for usage. The purpose is to improve interoperability between Call Agents and Gateways. Conventions used in this document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC-2119. Foster & Sivachelvan Informational [Page 1]
MGCP Return Code Usage February 2003 Table of Contents 1.0. Introduction.....................................................2 2.0. Return Code Usage................................................2 2.1. Return Code Categories.........................................2 2.2. Return Code Descriptions.......................................4 3.0. Guidelines for Usage............................................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 Although, some return codes in the Media Gateway Control Protocol MGCP 1.0 [2] are indications of very specific situations, others are more generic in nature. It is not possible, nor is it necessary, to come up with an error code for all possible error situations that might occur. Instead, the objective is to make sure that Call Agents behave the same for a given error situation that occurs in the gateway. This can be achieved if return codes are categorized according to a common expected behavior for the Call Agent. That way, if a certain situation occurs in the gateway that is not exactly described by one, and only one, of the return codes in MGCP 1.0, the gateway developer can choose the most appropriate error code based on how he/she expects the Call Agent should behave in that situation. This document does not describe exactly how Call Agents behave. That is left to the specific Call Agent implementation. All that it does is provide categories of errors and examples of their use. Note also that the focus is on return codes provided by gateways, resulting in certain behavior in the Call Agent (as opposed to the other way around). 2.0. Return Code Usage 2.1. Return Code Categories The following describes categorization of return codes from gateways based on expected Call Agent behavior. Category none (specific): A return code associated with a fairly specific situation in the gateway will likely invoke a Call Agent behavior that is very specific to that return code. As such, these return codes are not categorized into a common behavioral category. Foster & Sivachelvan Informational [Page 2]
MGCP Return Code Usage February 2003 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.), whether this is the originating or terminating endpoint in the call and possibly other information related to the call state. This document does not attempt to outline the Call Agent behaviors for these situations, but it does recommend that similar Call Agent behavior SHOULD be invoked for return codes in the same category, except for return codes in category "none". Foster & Sivachelvan Informational [Page 3]
MGCP Return Code Usage February 2003 A summary of the categories of the various return codes is included in the following table. This information is also repeated in the detailed error descriptions in the next section. ------------------------------------------------------------------ | Category | Return Codes | |-------------|----------------------------------------------------| | none | 000, 100, 101, 200, 250, 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" | | ------------------------------------------------------------------ * 404: may be treated as a "Temporary Failure" but specific behavior is possible (e.g. try an alternate codec with lower bandwidth requirement rather than failing this call). * 503: refer to the detailed description in section 2.2 of this document. Rather than treating it as a "Provisioning Mismatch", it is possible for the Call Agent to recover from this error. * 527: See the detailed description for this return code in section 2.2. This could be treated as a "State Mismatch" depending on the circumstances. * 528: See the detailed description for this return code in section 2.2. This could be treated as a "State Mismatch" depending on the circumstances. * 534: See the note on return 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). 2.2. Return Code Descriptions This section provides more detailed descriptions of return codes from MGCP 1.0 [2] with some example "situations" that may have triggered that return code, as well as the return code "category". Note that any indication that a response is valid for a NotificationRequest (RQNT) is also an indication that it is valid for a connection Foster & Sivachelvan Informational [Page 4]
MGCP Return Code Usage February 2003 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 [2]). Category: none (specific situation and behavior). 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 a small period of time, e.g. 200 ms, and hence may affect 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 [2]. 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: none (specific situation and behavior). 101 - Transaction has been queued for execution Response valid for: Any command. Situation: As described in [2], 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: none (specific situation and behavior). 200 - Transaction executed normally Response valid for: Any command (including DeleteConnection). Foster & Sivachelvan Informational [Page 5]
MGCP Return Code Usage February 2003 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: none (normal execution) 250 - The connection was deleted Response valid for: DeleteConnection. Situation: Response to a successful DeleteConnection command. Category: none (normal execution) 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 [3]. 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 [3]. It is also returned when requesting an incoming on- Foster & Sivachelvan Informational [Page 6]
MGCP Return Code Usage February 2003 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. 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. 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 [2], 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. Foster & Sivachelvan Informational [Page 7]
MGCP Return Code Usage February 2003 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 [2] 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 transactions at this time. In this case, the Call Agent SHOULD throttle back its request rate for this gateway as described in [2], 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 [2], 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). Foster & Sivachelvan Informational [Page 8]
MGCP Return Code Usage February 2003 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 [2], 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. Foster & Sivachelvan Informational [Page 9]
MGCP Return Code Usage February 2003 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 [2], 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 [4], 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. Foster & Sivachelvan Informational [Page 10]
MGCP Return Code Usage February 2003 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". 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 [2]. 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". Foster & Sivachelvan Informational [Page 11]
MGCP Return Code Usage February 2003 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 [2]. 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". 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. Foster & Sivachelvan Informational [Page 12]
MGCP Return Code Usage February 2003 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 [2]. 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. 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 [2] 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. Foster & Sivachelvan Informational [Page 13]
MGCP Return Code Usage February 2003 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 [2] that are either unknown, unsupported or an illegal combination as indicated in section 2.3.3 of [2]. Note that unsupported extension actions should generate error code 518 (unsupported package). 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. Foster & Sivachelvan Informational [Page 14]
MGCP Return Code Usage February 2003 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. 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. Foster & Sivachelvan Informational [Page 15]
MGCP Return Code Usage February 2003 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". 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. Foster & Sivachelvan Informational [Page 16]
MGCP Return Code Usage February 2003 Category: "Provisioning Mismatch" if the error resulted from an empty approved list of codes as described in [2], Section 2.6). "Remote Connection Descriptor Error" if the error resulted from an empty negotiated list of codecs, as described in [2], 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 [2] (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". 539 - Invalid or unsupported command parameter Foster & Sivachelvan Informational [Page 17]
MGCP Return Code Usage February 2003 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 [2]. 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". In the case where the error code is not recognized, the following behavior is assumed: 0XX - treated as a 000 (assumed to be a response acknowledgement). 1XX - treated as a 100 (provisional response), final response expected later. 2XX - treated as a 200 (successful response). 3XX - treated as a 521 (should only occur as a re-direct in response to a RestartInProgress message). 4XX - treated as a 400 (Category "Temporary Failure") 5XX -9XX - treated as a 510. Foster & Sivachelvan Informational [Page 18]
MGCP Return Code Usage February 2003 3.0. Guidelines for Usage 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) are 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 [2] (repeated at the end of section 2 in this document). * 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, Call Agents may have to treat these as 403, 405 and 404 respectively for gateways that have not been updated according to [2] 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 Foster & Sivachelvan Informational [Page 19]
MGCP Return Code Usage February 2003 presently used incorrectly but will be replaced with 403, 405 and 404 in the future). 4.0. Security Considerations No further security considerations are required beyond those indicated in the base MGCP specification [2]. 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] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997 [2] Andreasen and Foster, Media Gateway Control Protocol (MGCP) Version 1.0, RFC 3435, January 2003 [3] Foster and Andreasen, Basic MGCP Packages, work in progress, October 2002. [4] 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 February 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]