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