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,
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".
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.
520 - Endpoint is restarting.
Situation: This is normally a transient error in which error
code 405 SHOULD be used. Gateways SHOULD not use this error
code unless there is some relevant situation that warrants the
category of "Service Failure". Note that this was included in
[1] only to maintain backwards compatibility with previous
releases of the MGCP specification.
Category: If it is returned, this return code will be treated
as category "Service Failure", i.e., as if this endpoint is
out-of-service.
521 - Endpoint re-directed to another Call Agent.
Response valid for: RestartInProgress.
Situation: A RestartInProgress command was sent to the Call
Agent and the Call Agent returns this return code along with a
NotifiedEntity parameter pointing to another Call Agent. The
gateway then sends a new RestartInProgress command to the Call
Agent specified in the Notified Entity.
Category: none (specific situation and behavior).
522 - No such event or signal.
Response valid for: NotificationRequest.
Situation: This is returned if the requested event/signal name
is not registered with this package. If on the other hand the
signal or event is part of the package but is not supported by
the gateway, then return code 512 or 513 SHOULD be provided
instead. If the package is not supported, return code 518
SHOULD be returned.
Category: "Provisioning Mismatch".
523 - Unknown action or illegal combination of actions.
Response valid for: NotificationRequest with one or more
requested events.
Situation: Request was made with a requested event(s) that
included an action or actions defined in [1] that are either
unknown, unsupported or an illegal combination as indicated in
section 2.3.3 of [1]. Note that unsupported extension actions
should generate error code 518 (unsupported package).
Category: "Provisioning Mismatch".
524 - Internal inconsistency in Local Connection Options
Response valid for: CreateConnection, ModifyConnection.
Situation: This is returned if one or more of the
LocalConnectionOptions (LCO) parameters are coded with values
that are not consistent with each other (e.g., other LCO
parameters inconsistent with the network type).
Category: "Provisioning Mismatch".
525 - Unknown extension in Local Connection Options.
Response valid for: CreateConnection, ModifyConnection.
Situation: This is returned if the request contains a Local
Connection Option with one or more unrecognized mandatory ("x+")
extensions. Note that unsupported package extensions should use
error code 518 (unsupported package) instead.
Category: "Provisioning Mismatch".
526 - Insufficient bandwidth
Response valid for: CreateConnection, ModifyConnection.
Situation: In most cases where there is insufficient
bandwidth, a 404 return code should be used. 526 would be used
in cases where future requests are destined to fail. An example
might be a very restricted bandwidth case, where there is not
enough bandwidth available for the codec requested even for a
single endpoint. Making a request with the same codec in the
future will fail. However, making a request for some other
codec (with a higher degree of compression) may pass. For
cases, where the bandwidth is pooled over multiple endpoints and
could free up at some future time (because an endpoint becomes
inactive), then 404 is more appropriate.
Category: If it is returned, this return code will be treated
as category "Provisioning Mismatch", e.g., the codec was
incorrectly provisioned for the bandwidth available.
527 - Missing RemoteConnectionDescriptor.
Response valid for: CreateConnection, ModifyConnection,
NotificationRequest.
Situation: This is returned if the connection has not yet
received a RemoteConnectionDescriptor when one is required to
support the request. This can for example happen if a
connection is attempted to be placed in "send/receive mode", or
if a signal is applied on a connection.
Category: "Remote Connection Descriptor Error" in the case
where the other end did not provide a connection descriptor.
Alternatively, if this is an initial request made by a Call
Agent (such there is no remote connection descriptor), then this
is a "State Mismatch" problem.
528 -Incompatible protocol version
Response valid for: Any command.
Situation: A command was received with a protocol version that
was not supported.
Category: "Provisioning Mismatch". This could also be
treated as a "State Mismatch" problem if the there is a recovery
mechanism (e.g., Call Agent recognizes the protocol version
mismatch and switches to the correct protocol version)
529 - Internal Hardware Error.
Response valid for: Any command.
Situation: A hardware fault occurred during the execution of a
command such that repeating this command will result in a
failure indication once again. This is a slightly more specific
error code than error 502, although more commentary should be
provided (for debug purposes) if possible.
Category: "Service Failure".
530 - CAS Signaling Protocol Error.
Response valid for: NotificationRequest.
Situation: This is specific to Channel Associated Signaling
(CAS) interfaces. A typical example might be an attempt to
outpulse digits failed for some reason.
Category: none (specific situation and behavior).
531 - Failure of a grouping of trunks (e.g., facility failure)
Response valid for: CreateConnection, ModifyConnection,
NotificationRequest.
Situation: Request made to an endpoint that has a failed trunk
connection (e.g., T1 or E1 failed). Note that an RSIP should
have been sent as a result of the facility failure. This is a
more specific response than return code 501.
Category: "Service Failure".
532 - Unsupported value(s) in Local Connection Options.
Response valid for: CreateConnection, ModifyConnection.
Situation: This is returned if one or more of the
LocalConnectionOptions parameters are coded with a value that
the gateway does not support.
Category: "Provisioning Mismatch".
533 - Response too large
Response valid for: Any command.
Situation: This would only be likely to occur in the case of an
audit where the maximum response packet size would end up being
too large.
Category: none (specific situation and behavior).
534 - Codec negotiation failure
Response valid for: CreateConnection, ModifyConnection.
Situation: The intersection between the list of codecs that
the gateway supports, the codecs allowed by the local connection
options and the codecs supplied in the Remote Connection
Descriptor (if provided) is empty.
Category: "Provisioning Mismatch" if the error resulted from
an empty approved list of codes as described in [1], Section
2.6). "Remote Connection Descriptor Error" if the error
resulted from an empty negotiated list of codecs, as described
in [1], Section 2.6.
535 - Packetization period not supported
Response valid for: CreateConnection, ModifyConnection.
Situation: Normally this error should not be generated since
if the gateway is unable to support the packetization period
specified in the local connection options for the codec
indicated, it should follow the behavior specified in [1] (which
is to pick an appropriate value rather than failing the
request).
Category: "none".
536 - Unknown or unsupported Restart Method
Response valid for: RestartInProgress.
Situation: This error is generated by the Call Agent if it
receives a RestartInProgress command with an unsupported restart
method. Note that if the restart method is an extension restart
method, error code 518 (unsupported package) should be used
instead.
Category: "Provisioning Mismatch".
537 - Unknown or unsupported digit map extension
Response valid for: NotificationRequest.
Situation: Digit map letter in the digit map unknown or
unsupported. Note that this code does apply to extension digit
map letters as well.
Category: "Provisioning Mismatch".
538 - Event/signal parameter error
Response valid for: NotificationRequest.
Situation: It is returned if the event/signal parameter is in
error or not supported. If the event/signal or a package is not
supported, then one of 512, 513, 518, or 522 should be used
instead.
Category: "Provisioning Mismatch".
539 - Invalid or unsupported command parameter
Response valid for: Any command.
Situation: This is returned if the command contains an invalid
or unsupported parameter, which is neither a package (which
would use return code 518) nor vendor specific extension (which
would use return code 511). For example, if an endpoint does
not support the BearerInformation parameter of the
EndpointConfiguration command, this return code could be used.
Of course, such an implementation would not conform to [1].
Category: "Provisioning Mismatch".
540 - Per endpoint connection limit exceeded
Response valid for: CreateConnection.
Situation: A CreateConnection command was made, but the
gateway cannot support any additional connections on that
endpoint.
Category: "State Mismatch".
541 - Invalid or unsupported Local Connection Options
Response valid for: CreateConnection, ModifyConnection.
Situation: This is returned if the command contains an invalid
or unsupported LocalConnectionOption, which is neither a package
(which would use return code 518) nor vendor specific extension
(which would use return code 511).
Category: "Provisioning Mismatch".
2.3. Summary of Return Code Categories
A summary of the categories of the various error codes is included in
the following table. This information is also repeated in the
detailed error descriptions in the next section.
------------------------------------------------------------------
| Category | Return Codes |
|-------------|----------------------------------------------------|
| normal | 000, 100, 101, 200, 250 |
|-------------|----------------------------------------------------|
| none | 405, 407, 410, 510, 521, 530, 533, 535 |
|-------------|----------------------------------------------------|
| "Service | 501, 502, 520, 529, 531 |
| Failure" | |
|-------------|----------------------------------------------------|
|"Provisioning| 500, 503*, 504, 507, 508, 510, 511, 512, 513, 514, |
| Mismatch" | 517, 518, 522, 523, 524, 525, 526, 528*, 532, 534*,|
| | 536, 537, 538, 539, 541 |
|-------------|----------------------------------------------------|
| "Temporary | 400, 403, 404*, 405, 406, 409 |
| Failure" | |
|-------------|----------------------------------------------------|
| "State | 401, 402, 515, 516, 519, 540 |
| Mismatch" | |
|-------------|----------------------------------------------------|
| "Remote | 505, 506, 509, 527* |
| Connection | |
| Descriptor | |
| Error" | |
------------------------------------------------------------------
Notes:
* 404: may be treated as a "Temporary Failure", but specific
behavior is possible (e.g., trying an alternate codec with lower
bandwidth requirement rather than failing this call).
* 503: rather than treating this as a "Provisioning Mismatch", it is
possible for the Call Agent to recover from this error.
* 527: See the detailed description for this error code in section
2.2. This could be treated as a "State Mismatch" depending on the
circumstances.
* 528: See the detailed description for this error code in section
2.2. This could be treated as a "State Mismatch" depending on the
circumstances.
* 534: See the note on error code 534 in the detailed description
section (2.2) of this document (may be treated as a "Remote
Connection Descriptor Error" if no local connection options were
supplied).
3. Additional Guidelines
This section provides additional guidelines to Gateway and Call Agent
developers.
3.1. Gateway Recommendations
The following guidelines are recommended for gateway implementations:
* For uncategorized return codes (category "none") that involve
specific situations, gateways should make sure they do an accurate
mapping between the situation and the return code.
* Also for category "State Mismatch", it is equally important that
the situation (and state) is accurately mapped to the specific
error code.
* For situations similar to those involving return codes in "Service
Failure", Provisioning Mismatch", "Temporary Failure" and "Remote
Connection Descriptor Error" categories, the gateway should make
sure that it uses a return code in the correct category.
* MGCP allows additional commentary to be included with the return
code. It is important that the gateway includes more specific
information concerning the situation for debug purposes.
* It is recommended that return codes 502, 520 and 526 not be used
unless there is something that makes these permanent situations.
As indicated in the detailed description of these return codes,
403, 405 and 404 respectively are more appropriate in almost all
situations. If a gateway presently uses 502, 520 and 526 for
temporary situations and expects to upgrade to 403, 405 and 404,
the gateway should refrain from using 502, 520 and 526 for some
other use immediately after the upgrade. This is to avoid problems
where a Call Agent is expected to treat the same error code in two
different ways, e.g., 403 is a category "Temporary Failure" which
requires a different Call Agent behavior from 502 which is in
category "Service Failure".
3.2. Call Agent Recommendations
The following guidelines are recommended for gateway implementations:
* Call Agents should handle return codes they do not recognize (or
do not expect) based on the first digit in the return code as
outlined in [1].
* For categories "Service Failure", "Provisioning Mismatch",
"Temporary Failure", and "Remote Connection Descriptor Error",
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.