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