RFC 3661

Media Gateway Control Protocol (MGCP) Return Code Usage

📅 published December 2003, from ietf

RFC 3661: Media Gateway Control Protocol (MGCP) Return Code Usage 💖

Network Working Group 🌸 Request for Comments: 3661. Written by B. Foster and C. Sivachelvan from Cisco Systems in December 2003. Category: Informational 🧚. It updates RFC 3435, so it adds to that spec without replacing it.

Status of This Memo ✨

This memo gives information to the Internet community 🫶. It does not specify an Internet standard of any kind, and it can be shared freely with no distribution limits 🦋.

Copyright (C) The Internet Society (2003). All Rights Reserved 💅.

Abstract 🌈

Okay so this doc gives implementation guidelines for the return codes in RFC 3435, Media Gateway Control Protocol (MGCP) Version 1.0 🎀. The return codes in RFC 3435 don't cover every single situation a gateway could ever run into, and that's not possible or even needed 🙈. What really matters is that the Call Agent that gets a return code acts appropriately and consistently for whatever happened 👑. This document exists to help make sure that consistency happens ✨.

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 doc gives implementation guidelines for using return codes in the Media Gateway Control Protocol MGCP 1.0 [1] 🫧. Return codes in [1] don't cover every possible specific situation that could ever happen in the gateway. That's not possible and not necessary 🙃. What matters is that the Call Agent that gets that return code behaves appropriately and consistently for the situation that actually happened 💅. The solution here is to sort the return codes gateways send into categories, based on how the Call Agents that receive them are expected to behave 🔥.

Sorting errors into categories is honestly so helpful for both Call Agent and gateway developers 😭. It helps gateway developers pick a good return code when a specific one for their situation doesn't exist ✨. It also helps Call Agent developers make sure the return code they receive gets handled consistently 🫶.

1.2. Document Organization 🗂️

Along with the categories (section 2.1), section 2.2 gives a consolidated list of return codes, described in terms of the "situations" that may have triggered them and the "categories" they fall under 💖. That comes with some extra implementation guidelines for using these codes 🌸. Section 2.3 has a summary of the return codes and their categories 🧚. Section 3 has more implementation guidelines for Call Agent and gateway developers 👑.

2. Return Code Usage 💜

2.1. Return Code Categories 🌈

Here's how return codes from gateways get categorized, based on how the Call Agent is expected to behave 🎀:

  • Category normal: These return codes are used in normal operation and don't represent error conditions 🫧.
  • Category none (specific errors requiring specific action): A return code tied to a specific situation in the gateway that will trigger a matching specific Call Agent behavior 🎯. Because of that, these return codes don't get sorted into a shared behavioral category 🙈.
  • Category "Service Failure": A category where the endpoint is either out-of-service, or the Call Agent is expected to treat it the same way it treats an out-of-service endpoint 💀.
  • Category "Provisioning Mismatch": A situation where the gateway says it doesn't support what the Call Agent asked it to do 🥺. This can happen when the provisioning of the Call Agent and the gateway isn't in sync 🔄. Note that you should try to weed out these kinds of errors during integration testing 🧹.
  • Category "Temporary Failure": This error is temporary, so this particular call is likely to be permanently affected, but later calls on the same endpoint may go through just fine 🦋. The situation that caused it usually won't go away unless something changes in the gateway or network, like more bandwidth opening up or more CPU resources becoming free 💻. This won't change in a few tens of milliseconds 😌. It could change within some number of seconds or minutes, as resources free up, which is about the time you'd expect before trying a different call on that endpoint ⏳.
  • Category "State Mismatch": A state mismatch between the Call Agent and the gateway, which the Call Agent can fix by making a request that better fits the gateway's state 🔧. It shares a common category name, but the Call Agent's behavior depends on the situation, like what kind of state mismatch happened and other state info such as call state 🧠.
  • Category "Remote Connection Descriptor Error": This means there's some mismatch between the two gateways involved in the call 📡. Per RFC 2327, all gateways should ignore SDP attributes they don't recognize, so not recognizing an SDP attribute should never be the reason for an error indication 🙅‍♀️.

The exact Call Agent behavior for the categories above can depend on the type of endpoint (analog, ISUP trunk, CAS trunk, etc.), whether it's the originating or terminating endpoint in the call, and possibly other call state info 🔍. This document doesn't try to spell out Call Agent behavior based on call state 🤷‍♀️. Instead, it just recommends that Call Agent behavior stay consistent based on the combo of call state and the specific category of error received 🫶.

2.2. Return Code Situations and Categories 🎀

This section describes the return codes in MGCP 1.0 [1] in terms of the "situations" that may have triggered each code and the "categories" each code belongs to 💖. The goal is to give developers extra guidelines for using return codes 🌸.

Quick heads up: if a response is valid for a NotificationRequest (RQNT), it's also valid for a connection handling request, meaning CRCX, MDCX, or DLCX with an encapsulated RQNT ✨. The same goes for the 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 has 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 might take a long transaction execution time, e.g., more than 200 ms 🐢.
  • Situation: When a transaction is expected to take more processing time than the normal retry timer allows, the gateway sends a provisional response 🕰️. A final response comes later, once the transaction is done. Refer to section 3.5.6 of [1] 📖. An example is a CreateConnection command using RSVP, where making the connection could take longer than usual because the network resource reservation has to happen 🌐.
  • Category: normal 💫.

101 - Transaction has been queued for execution 🚦

  • Response valid for: Any command 🌍.
  • Situation: As described in [1], Section 4.4.8, Call Agents and gateways conceptually keep a queue of incoming transactions to run 📋. That queue has a high-water mark and a low-water mark 🌊. Once the queue length hits the high-water mark, the entity should start sending 101 provisional responses (transaction queued) until the queue length drops to the low-water mark 📉. This applies to new transactions and to retransmissions alike 🔁. A final response comes later, after the transaction is complete 🏁. 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: This is the normal response for a successful execution 🥳. The 250 response code can be used to acknowledge that a DeleteConnection command finished successfully 🧡. A 200 response code is also appropriate there 🫶.
  • Category: normal 🌟.

250 - The connection was deleted 🗑️

  • Response valid for: DeleteConnection 🎯.
  • Situation: This is the response to a successful DeleteConnection command 👋.
  • Category: normal 🌼.

400 - Unspecified transient error 😵‍💫

  • Response valid for: Any command 🌐.
  • Situation: This is an unspecified transient error. A more specific error code should be used if one is available, since this code gives very little info 🙁. If it's used, some specific commentary should be included to help with debugging 🔎.
  • Category: "Temporary Failure" ⚠️.

401 - The phone is already off-hook 📞

  • Response valid for: NotificationRequest 📨.
  • Situation: This comes back when there's a request for an off-hook transition requested event but the phone is already off-hook 📴. It also comes back when a request is made to generate a signal that has an explicit on-hook precondition in its signal definition, like the ringing signal ("rg") in the Line package [2] 🔔. And it comes back when requesting an incoming off-hook/seizure indication for a Channel Associated Signaling (CAS) trunk whose incoming hook-state is already off-hook 🚪.
  • Category: "State Mismatch". If the Call Agent makes the request with a requested event that indicates a different hook-state, the request shouldn't get this return code again 🙌.

402 - The phone is already on-hook 📴

  • Response valid for: NotificationRequest 📨.

To be continued 🌈✨

Situation: okay so this one gets thrown when the Call Agent asks for an on-hook or hook-flash requested event but the phone is already on-hook 📞 It also pops up when someone requests a signal that has an explicit off-hook precondition in its definition, like the dial tone (dl) in the Line package [2] 🎀 And it's returned when you ask for an incoming on-hook indication on a CAS trunk whose incoming hook-state 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 can't be processed because the gateway is temporarily short on resources, like CPU utilization, DSP resources, memory etc 🖥️ The command might succeed later when resources free up ✨ 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 isn't enough bandwidth available to sustain the call 📉 It's the result of some failed bandwidth check (could be RSVP or some other mechanism) 🧐 It's possible the Call Agent could request a codec requiring lower bandwidth and get a successful result 🦋 Alternatively, it could treat this as a "Temporary Failure" for this codec 🤷‍♀️

Category: "Temporary Failure". Although it's categorized under this general category, 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: this 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 hasn't completed yet ⏳ If the request is made at a later time, it may be "successful" but might not be appropriate (because of a 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 got aborted 🛑 An example might be a transaction where a provisional response (100 response code) was returned. After that, the gateway decided the actual transaction was taking longer than should reasonably be expected, so it aborted and returned 406 as the final response 😭

Category: "Temporary Failure". If this error code keeps getting returned, 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: the gateway is overloaded (e.g., too many requests per second from the Call Agent) and can't process any more transactions right now 🥵 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". The Call Agent's behavior with respect to the call being set up does fit this general category, but there's some specific Call Agent behavior implied too (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 it 🥲 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's no endpoint matching the EndpointId provided with the command 👀 This could be a provisioning mismatch between the Call Agent and the gateway, or a card was removed from the gateway so the endpoint is no longer available (in which case a RestartInProgress should be received, although the Call Agent can't depend on this) 🃏 Note that the endpoint isn't just out-of-service (in which case 501 would be used); it's 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 🛠️ That includes maintenance states such as out-of-service. Note that an endpoint that has initiated the restart procedure is in-service, so it should not use this return code, even if the restart procedure hasn't completed yet (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 doesn't 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 can't be processed with that wildcarding 🌀 An example would be a NotificationRequest with a request where a failure would make it too difficult to roll back the state of all the endpoints to what they were before 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 isn't 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 aren't 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 clash with each other and/or can't 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's 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 isn't 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 doesn't support or doesn't recognize the requested quarantine handling 🛡️

Category: "Provisioning Mismatch" 🧩

509 - Error in RemoteConnectionDescriptor

Response valid for: CreateConnection, ModifyConnection.

Situation: there's a syntax or semantic error in the Remote Connection Descriptor 📝 For example, there's 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 gives very little information. If it's used, some specific commentary should be included to help with debugging 🔍

Category: "Provisioning Mismatch" 🧩

511 - Unrecognized parameter extension.

Response valid for: Any command.

Situation: this 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, but the gateway isn't equipped to detect it (i.e., the package is only implemented partially) 🧱 Of course, an implementation like that wouldn't 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, but the gateway isn't equipped to generate it, because the package is only partly implemented. ngl, an implementation like that would not conform to [1] 😭. If the signal is invalid (not defined in the relevant package), use error code 522. If the package itself is unknown or unsupported, use error code 518 🎀.
  • 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 very specific vibe about playing announcements on an endpoint, or on a connection tied to that 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 got specified. It's possible the connection was already deleted, bestie 💀. A connection-id can also show up with events and signals (e.g., "S: L/rt@connId"). A mismatch between connection-id and call-id should use error code 516 instead 🙈.
  • Category: "State Mismatch"

516 - Unknown or incorrect call-id. 🧚

  • Response valid for: ModifyConnection, DeleteConnection.
  • Situation: Either the call-id is unknown, or it's incorrect. For example, the connection-id isn't associated with this call-id 😤.
  • Category: "State Mismatch"

517 - Invalid or unsupported mode. 🌈

  • Response valid for: CreateConnection, ModifyConnection.
  • Situation: This gets returned if the command asks for a connection mode the endpoint doesn't support. Not every endpoint supports every mode, so no shade 💅. 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 in the request isn't supported, or it's unknown. The package name might also be a prefix to an event or other things (e.g., a parameter), as defined in [1] ✨. 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: Someone asked the endpoint to detect digits using a digit map, but the gateway doesn't have one 😭.
  • 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, and error code 405 SHOULD be used. Gateways SHOULD not use this error code unless there's a relevant situation that warrants the category of "Service Failure" 🎀. This code was included in [1] only to keep backwards compatibility with earlier MGCP releases 🕰️.
  • Category: If it does get returned, it's treated as category "Service Failure", which means the endpoint is basically out-of-service 🥲.

521 - Endpoint re-directed to another Call Agent. 🦋

  • Response valid for: RestartInProgress.
  • Situation: A RestartInProgress command got sent to the Call Agent, and the Call Agent returns this code along with a NotifiedEntity parameter pointing to a different Call Agent. Then the gateway 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 gets returned if the requested event or signal name isn't registered with this package. If the signal or event is part of the package but the gateway doesn't support it, return code 512 or 513 SHOULD be provided instead 👀. If the package isn't 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: The request had requested event(s) with 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]. 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 gets returned if one or more of the LocalConnectionOptions (LCO) parameters have values that don't match each other. For example, other LCO parameters might not fit the network type 🌐.
  • Category: "Provisioning Mismatch"

525 - Unknown extension in Local Connection Options. 🎀

  • Response valid for: CreateConnection, ModifyConnection.
  • Situation: This gets returned if the request has a Local Connection Option with one or more unrecognized mandatory ("x+") extensions. Unsupported package extensions should use error code 518 (unsupported package) instead 🙃.
  • Category: "Provisioning Mismatch"

526 - Insufficient bandwidth 🌊

  • Response valid for: CreateConnection, ModifyConnection.
  • Situation: Most of the time, when there isn't enough bandwidth, a 404 return code should be used. Code 526 is for when future requests are destined to fail too 😬. Picture a super restricted bandwidth situation where there isn't enough for the requested codec, even for a single endpoint. Asking for that same codec later will fail again. But asking for a different codec with a higher degree of compression might pass 🗜️. When the bandwidth is pooled across multiple endpoints and could free up later (say an endpoint goes inactive), then 404 is the better fit 🎯.
  • Category: If it does get returned, it's treated as category "Provisioning Mismatch", for example when the codec was incorrectly provisioned for the bandwidth available 🧾.

527 - Missing RemoteConnectionDescriptor. 🔍

  • Response valid for: CreateConnection, ModifyConnection, NotificationRequest.
  • Situation: This gets returned if the connection hasn't received a RemoteConnectionDescriptor yet, but one is needed to support the request. This can happen if someone tries to put a connection in "send/receive mode", or if a signal gets applied on a connection 📡.
  • Category: "Remote Connection Descriptor Error" when the other end didn't provide a connection descriptor. But if this is an initial request from a Call Agent (so there's no remote connection descriptor yet), then it's a "State Mismatch" problem 🤷‍♀️.

528 -Incompatible protocol version 🌀

  • Response valid for: Any command.
  • Situation: A command came in with a protocol version that isn't supported 🙅‍♀️.
  • Category: "Provisioning Mismatch". This could also be treated as a "State Mismatch" problem if there's a recovery mechanism, like when the Call Agent notices the version mismatch and switches to the correct protocol version 🔄.

529 - Internal Hardware Error. ⚡

  • Response valid for: Any command.
  • Situation: A hardware fault happened while the command was running, so repeating the command will fail again 😵. This is a slightly more specific version of error 502, although more commentary should be provided (for debugging) 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 would be an attempt to outpulse digits that 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: A request got made to an endpoint with a failed trunk connection, like a T1 or E1 that went down 📉. 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 gets returned if one or more of the LocalConnectionOptions parameters are coded with a value the gateway doesn't support 🚫.
  • Category: "Provisioning Mismatch"

533 - Response too large 📦

  • Response valid for: Any command.
  • Situation: This would only really happen during 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 overlap between three lists is empty: the codecs the gateway supports, the codecs allowed by the local connection options, and the codecs supplied in the Remote Connection Descriptor (if one was provided) 🫥.
  • Category: "Provisioning Mismatch" if the error came from an empty approved list of codes, as described in [1], Section 2.6). "Remote Connection Descriptor Error" if it came 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 shouldn't be generated. If the gateway can't support the packetization period given in the local connection options for the codec, it should follow the behavior specified in [1] instead, 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: The Call Agent generates this error if it receives a RestartInProgress command with an unsupported restart method. If the restart method is an extension restart method, error code 518 (unsupported package) should be used instead 🧩.
  • Category: "Provisioning Mismatch"

Okay so, 537 through 541 are all about the gateway saying "nope, can't do that" for different reasons. 💅

537 - Unknown or unsupported digit map extension 🔢

Response valid for: NotificationRequest.

Situation: The digit map letter in the digit map is unknown or unsupported. Note that this code also applies to extension digit map letters. 🧩

Category: "Provisioning Mismatch".

538 - Event/signal parameter error 🚨

Response valid for: NotificationRequest.

Situation: This 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. It's not a package (that would be 518) and not a vendor specific extension (that would be 511). For example, if an endpoint doesn't 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. It's full, bestie. 🫶

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. It's not a package (that would be 518) and not a vendor specific extension (that would be 511).

Category: "Provisioning Mismatch".

2.3. Summary of Return Code Categories 📋

Here's a cute little cheat sheet of all the categories. The detailed descriptions in the last section repeat this info, so you're covered either way. ✨

 ------------------------------------------------------------------
|  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 gives extra guidelines to Gateway and Call Agent developers. Read it, bestie, it's the good stuff. 👑

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". 🚫 Don't reuse the old codes for something new, or the Call Agent gets confused and that's a whole mess. 😭

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. 🛡️ So no panic, the security is fine. 💖

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.

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

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

📦 where this page comes from