idnits 2.17.1 draft-foster-mgcp-returncodes-03.txt: -(405): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. == There is 1 instance of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 362: '...e. In this case, the Call Agent SHOULD...' RFC 2119 keyword, line 379: '... assigned MUST be in-service and...' RFC 2119 keyword, line 482: '...lity. Note that this error code SHOULD...' RFC 2119 keyword, line 644: '... code 405 SHOULD be used. Gatewa...' RFC 2119 keyword, line 673: '...urn code 512 or 513 SHOULD be provided...' (1 more instance...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: 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. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (August 2003) is 7559 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Missing reference section? '1' on line 1052 looks like a reference -- Missing reference section? '2' on line 1054 looks like a reference -- Missing reference section? '3' on line 1057 looks like a reference Summary: 4 errors (**), 0 flaws (~~), 3 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Internet Engineering Task Force B. Foster 2 Internet Draft C. Sivachelvan 3 Document: Cisco Systems 4 Category: Informational August 2003 6 Media Gateway Control Protocol (MGCP) Return Code Usage 8 Status of this Document 10 This document is an Internet-Draft and is in full conformance with 11 all provisions of Section 10 of RFC2026 13 Internet-Drafts are working documents of the Internet Engineering 14 Task Force (IETF), its areas, and its working groups. Note that other 15 groups may also distribute working documents as Internet-Drafts. 17 Internet-Drafts are draft documents valid for a maximum of six months 18 and may be updated, replaced, or obsoleted by other documents at any 19 time. It is inappropriate to use Internet-Drafts as reference 20 material or to cite them other than as "work in progress." 22 The list of current Internet-Drafts can be accessed at 23 http://www.ietf.org/ietf/1id-abstracts.txt 25 The list of Internet-Draft Shadow Directories can be accessed at 26 http://www.ietf.org/shadow.html. 28 Abstract 30 This document provides implementation guidelines for the use of 31 return codes in the Media Gateway Control Protocol MGCP 1.0 (RFC 32 3435). Return codes in RFC 3435 do not cover all possible specific 33 situations that may ever occur in a gateway. That is not possible and 34 not necessary. What is important is to ensure that the Call Agent 35 that receives a return code behaves appropriately and consistently 36 for the given situation. The purpose of this document is to provide 37 implementation guidelines to ensure that consistency. 39 MGCP Return Code Usage August 2003 41 Table of Contents 42 1.0. Introduction.....................................................2 43 1.2. Document Organization...........................................2 44 2.0. Return Code Usage................................................3 45 2.1. Return Code Categories..........................................3 46 2.2. Return Code Situations and Categories...........................4 47 2.3. Summary of Return Code Categories..............................18 48 3.0. Additional Guidelines...........................................19 49 3.1. Gateway Recommendations........................................19 50 3.2. Call Agent Recommendations.....................................19 51 4.0. Security Considerations.........................................20 52 5.0. Acknowledgements................................................20 53 6.0. References......................................................20 54 7.0. Authors' Addresses..............................................20 55 8.0. Full Copyright Statement........................................21 56 Acknowledgement......................................................21 58 1.0. Introduction 60 This document provides implementation guidelines for the use of 61 return codes in the Media Gateway Control Protocol MGCP 1.0 [1]. 62 Return codes in [1] do not cover all possible specific situations 63 that may ever occur in the gateway. That is not possible and not 64 necessary. What is important is to ensure that the Call Agent that 65 receives that return code behaves appropriately and consistently for 66 the situation that occurred. The solution described in this document 67 is to categorize return codes that gateways return based on the 68 expected behavior for the Call Agents that receive them. 70 Categorizing errors helps both Call Agent and gateway developers: it 71 helps gateway developers choose an appropriate return code when a 72 specific one for the situation is not available; it also helps Call 73 Agent developers ensure that there is consistent behavior for the 74 return code that is received. 76 1.2. Document Organization 78 In addition to categorizing return codes (section 2.1), section 2.2 79 provides a consolidated list of return codes in terms of "situations" 80 that may have triggered and the "categories" that they fall under. 81 This provides some additional implementation guidelines for the use 82 of these return codes. Section 2.3 includes a summary of the return 83 codes and their categories. Section 3 provides some additional 84 implementation guidelines for Call Agent and gateway developers. 86 MGCP Return Code Usage August 2003 88 2.0. Return Code Usage 90 2.1. Return Code Categories 92 The following categorizes return codes from gateways based on 93 expected Call Agent behavior. 95 Category normal: These return codes are used in normal operation and 96 do not represent error conditions. 98 Category none (specific errors requiring specific action): A return 99 code associated with a specific situation in the gateway that will 100 invoke a corresponding specific Call Agent behavior. As such, these 101 return codes are not categorized into a common behavioral category. 103 Category "Service Failure": A category in which the endpoint is 104 either out-of-service or the treatment by the Call Agent is expected 105 to be the same as for an out-of-service endpoint. 107 Category "Provisioning Mismatch": A situation where the gateway has 108 indicated that it does not support what the Call Agent has asked it 109 to do. This may be caused by a lack of synchronization between the 110 provisioning of the Call Agent and the gateway. Note that attempts 111 should be made to weed out these types of error situations during 112 integration testing. 114 Category "Temporary Failure": The transient nature of this error is 115 such that this particular call is likely to be permanently affected 116 but later calls on the same endpoint may proceed successfully. 117 Typically the situation that caused this error is not going to 118 disappear unless there is some change in state in the gateway or 119 network (e.g. more bandwidth becomes available, more CPU resources 120 become available etc.). This situation is not likely to change in a 121 few 10's of milliseconds but could change within some number of 122 seconds or minutes later (as resources become free), i.e., within the 123 time period that you might expect a different call to be tried on 124 that endpoint. 126 Category "State Mismatch": A case where there is a state mismatch 127 between the Call Agent and the gateway that can be resolved by the 128 Call Agent making a request that is more appropriate to the gateway 129 state. Although categorized with a common category indicator the 130 behavior of the Call Agent will depend on the situation (the type of 131 state mismatch that has occurred as well as other state information, 132 e.g., call state). 134 Category "Remote Connection Descriptor Error": This indicates some 135 mismatch between the two gateways involved in the call. Note that per 136 RFC 2327 all gateways should ignore SDP attributes that they do not 137 recognize (i.e., lack of recognition of an SDP attribute should not 138 be the cause of an error indication). 140 The exact behavior of the Call Agent for the above categories may 141 depend on the type of endpoint (analog, ISUP trunk, CAS trunk, etc.), 142 MGCP Return Code Usage August 2003 144 whether this is the originating or terminating endpoint in the call 145 and possibly other information related to call state. This document 146 does not attempt to outline the Call Agent behavior based on call 147 state. Instead, it just recommends that the Call Agent behavior be 148 consistent based on a combination of call state and the specific 149 category of error received. 151 2.2. Return Code Situations and Categories 153 This section describes return codes in MGCP 1.0 [1] in terms of 154 "situations" that may have triggered that return code and 155 "categories" to which the return code belongs. The purpose is to 156 provide developers additional guidelines for return code use. 158 Note that any indication that a response is valid for a 159 NotificationRequest (RQNT) is also an indication that it is valid for 160 a connection handling request, i.e. CreateConnection (CRCX), 161 ModifyConnection (MDCX), or DeleteConnection(DLCX) with an 162 encapsulated RQNT. The same holds for the EndpointConfiguration 163 (EPCF) command. 165 000 - Response acknowledgement 167 Response valid for: Confirmation of a final response after a 168 provisional response (3-way handshake). 170 Situation: If the final response that follows a provisional 171 response contains an empty response acknowledgement parameter, a 172 Response Acknowledgement is used to acknowledge the final 173 response (section 3.5.6 of [1]). 175 Category: normal. 177 100 - Transaction in progress 179 Response valid for: Any command that may result in a long 180 transaction execution time, e.g. more than 200 ms. 182 Situation: When a transaction is expected to take a processing 183 time that is beyond the normal retry timer, the gateway will 184 return a provisional response. A final response will be provided 185 later, after the transaction has completed. Refer to section 186 3.5.6 of [1]. An example of this might be a CreateConnection 187 command using RSVP, where the time to create the connection may 188 be longer than usual because of the need to perform the network 189 resource reservation. 191 Category: normal. 193 MGCP Return Code Usage August 2003 195 101 - Transaction has been queued for execution 197 Response valid for: Any command. 199 Situation: As described in [1], Section 4.4.8, we assume that 200 Call Agents and gateways conceptually maintain a queue of 201 incoming transactions to be executed. Associated with this 202 transaction queue is a high-water and a low-water mark. Once 203 the queue length reaches the high-water mark, the entity should 204 start issuing 101 provisional responses (transaction queued) 205 until the queue length drops to the low-water mark. This 206 applies to new transactions as well as to retransmissions. A 207 final response will be provided later, after the transaction has 208 completed. In this case, the Call Agent should throttle back its 209 request rate for this gateway. 211 Category: normal. 213 200 - Transaction executed normally 215 Response valid for: Any command (including DeleteConnection). 217 Situation: Normal response as a result of successful 218 execution. The 250 response code can be used to acknowledge a 219 successful completion of a DeleteConnection command. However, a 220 200 response code is also appropriate. 222 Category: normal 224 250 - The connection was deleted 226 Response valid for: DeleteConnection. 228 Situation: Response to a successful DeleteConnection command. 230 Category: normal 232 400 - Unspecified transient error 233 Response valid for: Any command. 235 Situation: Unspecified transient error. A more specific error 236 code should be used if one is available since this error code 237 provides very little information. If used, some specific 238 commentary should be included to aid in debug. 240 Category: "Temporary Failure". 242 401 - The phone is already off-hook 244 Response valid for: NotificationRequest. 246 Situation: This is returned in response to a request for an 247 off-hook transition requested event when the phone is already 248 off-hook. It is also returned when a request is made to generate 249 MGCP Return Code Usage August 2003 251 a signal that has an explicit on-hook precondition in the signal 252 definition, such as the ringing signal ("rg") in the Line 253 package [2]. It is also returned when requesting an incoming 254 off-hook/seizure indication for a Channel Associated Signaling 255 (CAS) trunk when the incoming hook-state for that trunk is 256 already off-hook. 258 Category: "State Mismatch". If the Call Agent makes the request 259 with a requested event indicating a different hook-state, the 260 request should not result in this return code again. 262 402 - The phone is already on-hook 264 Response valid for: NotificationRequest. 266 Situation: This is returned in response to a request for an 267 on-hook or hook-flash requested event when the phone is already 268 on-hook. It is also returned when a request is made to generate 269 a signal that has an explicit off-hook precondition in the 270 signal definition, such as the dial tone ("dl") in the Line 271 package [2]. It is also returned when requesting an incoming on- 272 hook indication for a CAS trunk when the incoming hook-state for 273 that trunk is already on-hook. 275 Category: "State Mismatch". If the Call Agent makes the 276 request with a requested event indicating a different hook- 277 state, the request should not result in this error again. 279 403 - Insufficient resources available at this time 281 Response valid for: Any command. 283 Situation: This is returned if the request cannot be processed 284 due to a temporary lack of gateway resources, such as CPU 285 utilization, DSP resources, memory etc; however, the command may 286 succeed at a later time when resources free up. Note that lack 287 of network resources should not result in this code (i.e. return 288 code 404 would be more appropriate). 290 Category: "Temporary Failure". 292 404 - Insufficient bandwidth at this time. 294 Response valid for: CreateConnection, ModifyConnection. 296 Situation: This is an indication that there is not enough 297 bandwidth available to sustain the call. It is as a result of 298 some failed bandwidth check (could be RSVP or some other 299 mechanism). It is possible that the Call Agent could request a 300 codec requiring lower bandwidth codec and have a successful 301 result. Alternatively it could treat this as a "Temporary 302 Failure" for this codec. 304 MGCP Return Code Usage August 2003 306 Category: "Temporary Failure". Although categorized under 307 this general category, note that the Call Agent could apply some 308 specific behavior (try a lower bandwidth codec) depending on 309 policy. 311 405 - Endpoint is restarting 313 Response valid for: Any command. 315 Situation: It may be returned to requests made when the 316 endpoint is in-service and has initiated the restart procedures 317 (see [1], Section 4.4.6) but the procedure has not yet 318 completed. If the request is made at a later time, it may be 319 "successful" but may not be appropriate (because of possible 320 state mismatch). The Call Agent should proceed after it believes 321 the restart procedure has completed. 323 Category: " Temporary Failure" 325 406 - Transaction Timeout 327 Response valid for: Any command. 329 Situation: The transaction took longer than expected and has 330 been aborted. An example might be a transaction where a 331 provisional response (100 response code) was returned. Following 332 that, the gateway determined that the actual transaction was 333 taking longer than should reasonably be expected and as a result 334 it aborted the transaction and returned 406 as the final 335 response. 337 Category: "Temporary Failure". If this error code is returned 338 repeatedly, it could indicate a more serious problem. 340 407 - Transaction aborted by some external action. 342 Response valid for: Any command. 344 Situation: This is returned to indicate cancellation of a 345 pending request (see [1] Section 4.4.4). For example, 346 DeleteConnection is received while processing a CreateConnection 347 or ModifyConnection. Also, if either a ModifyConnection, 348 NotificationRequest, or EndpointConfiguration command is in 349 progress, and the same command is received with a different 350 transaction Id, 407 will be returned. 352 Category: none (specific situation and behavior). 354 409 - Internal overload 356 Response valid for: Any command. 358 Situation: Gateway is overloaded (e.g. too many requests per 359 second from the Call Agent) and is unable to process any more 360 MGCP Return Code Usage August 2003 362 transactions at this time. In this case, the Call Agent SHOULD 363 throttle back its request rate for this gateway as described in 364 [1], Section 4.4.8. 366 Category: "Temporary Failure". Note that although the Call 367 Agent behavior with respect to the call being set up corresponds 368 to this general category, there is some specific Call Agent 369 behavior implied as well (i.e. the Call Agent throttling back). 371 410 - No endpoint available 373 Response valid for: CreateConnection using an "any of" wildcard. 375 Situation: A CreateConnection request was made with an "any 376 of" ("$") wildcard and no endpoint was available to execute the 377 request. As described in [1], Section 2.3.5, when the "any of" 378 wildcard is used with the CreateConnection command, the endpoint 379 assigned MUST be in-service and MUST NOT already have any 380 connections on it. 382 Category: none (specific situation and behavior). 384 500 - Endpoint unknown 386 Response valid for: Any command. 388 Situation: There is no endpoint matching the EndpointId 389 provided with the command. This could be the result of a 390 provisioning mismatch between the Call Agent and the gateway or 391 it could be because a card was removed from the gateway so that 392 the endpoint is no longer available (in which case a 393 RestartInProgress should be received, although the Call Agent 394 cannot depend on this). Note that the endpoint is not just out- 395 of-service (in which case 501 would be used); it is completely 396 unknown/unavailable to the MGCP. 398 Category: "Provisioning Mismatch". 400 501 - Endpoint is not ready or is out of service 402 Response valid for: Any command. 404 Situation: This is returned if the endpoint is in a permanent 405 �not ready� state. This includes maintenance states such as out- 406 of-service. Note that an endpoint that has initiated the restart 407 procedure is in-service, and hence should not use this return 408 code, even if the restart procedure has not yet completed (see 409 [1], Section 4.4.5). 411 Category: "Service Failure". 413 MGCP Return Code Usage August 2003 415 502 - Insufficient resources (permanent). 417 Response valid for: Any command. 419 Situation: This is returned when the endpoint does not have 420 sufficient resources and future requests on this endpoint are 421 expected to fail, meaning some resources dedicated to the 422 endpoint are broken (e.g. return code 529 - "hardware failure" 423 might be a more specific indication). For situations where 424 resources may become available in the future (i.e. resources are 425 pooled and not available at the present time), return code 403 426 should be used instead. 428 Category: "Service Failure". 430 503 - "All of" wildcard too complicated. 432 Response valid for: Any command. 434 Situation: This is returned when the wildcard convention used 435 in the request is understood, but the requested command cannot 436 be processed with the specified wildcarding. An example of this 437 would be a NotificationRequest with a request such that a 438 failure would make it too difficult to roll back the state of 439 all the endpoints to what they were prior to the request. 441 Category: Normally treated as a "Provisioning Mismatch". Note 442 however, that the Call Agent could treat it differently by 443 recovering with some specific behavior (e.g. generate a number 444 of individual requests without wildcards instead of a single one 445 with the wildcard). 447 504 - Unknown or unsupported command. 449 Response valid for: Any unknown command. 451 Situation: A command was requested other than those specified 452 in the MGCP specification [1], and the command is not supported. 454 Category: "Provisioning Mismatch". 456 505 - Unsupported remote connection descriptor. 458 Response valid for: CreateConnection, ModifyConnection. 460 Situation: One or more mandatory parameters or values in the 461 RemoteConnectionDescriptor are not supported by the gateway. 462 Note that, per [3], unsupported attribute lines must be ignored 463 and hence should not result in any errors. 465 Category: "Remote Connection Descriptor Error". 467 MGCP Return Code Usage August 2003 469 506 - Inability to satisfy both local connection options and remote 470 connection descriptor simultaneously. 472 Response valid for: CreateConnection, ModifyConnection. 474 Situation: The LocalConnectionOptions and 475 RemoteConnectionDescriptor contain one or more mandatory 476 parameters or values that conflict with each other and/or cannot 477 be supported at the same time (except for codec negotiation 478 failure - see error code 534). 480 Category: "Remote Connection Descriptor Error". 482 507 - Unsupported Functionality. Note that this error code SHOULD 483 only be used if there is no other more specific error code for 484 the unsupported functionality. 486 Response valid for: Any command. 488 Situation: Any situation where a request from the Call Agent 489 is not supported by the gateway - beyond the situations already 490 covered by other more specific return codes. 492 Category: "Provisioning Mismatch". 494 508 - Unknown or unsupported quarantine handling. 496 Response valid for: NotificationRequest. 498 Situation: The endpoint does not support or does not recognize 499 the requested quarantine handling. 501 Category: "Provisioning Mismatch". 503 509 - Error in RemoteConnectionDescriptor 505 Response valid for: CreateConnection, ModifyConnection. 507 Situation: There is a syntax or semantic error in the Remote 508 Connection Descriptor. For example, there is no IP address for 509 an RTP media stream. 511 Category: "Remote Connection Descriptor Error". 513 510 - Protocol error 515 Response valid for: Any command. 517 Situation: Some unspecified protocol error was detected. 518 Gateways should use this error as a last resort since it 519 provides very little information. If used, some specific 520 commentary should be included to aid in debug. 522 Category: "Provisioning Mismatch". 524 MGCP Return Code Usage August 2003 526 511 - Unrecognized parameter extension. 528 Response valid for: Any command. 530 Situation: It is returned if the requested command contains an 531 unrecognized mandatory parameter extension ("X+"). In MGCP 1.0, 532 this specifically refers to unrecognized parameters, since other 533 error codes are available for unrecognized connection modes 534 (517), unrecognized packages (518), unrecognized local 535 connection options (541), etc. 537 Category: "Provisioning Mismatch". 539 512 - Gateway not equipped to detect one of the requested events. 541 Response valid for: NotificationRequest. 543 Situation: A valid event was requested however the gateway is 544 not equipped to detect this event (i.e., the package is only 545 implemented partially). Of course, such an implementation would 546 not conform to [1]. Note that if an invalid event was requested, 547 i.e., an event not defined in the relevant package, then error 548 code 522 should be used. Also note, that if the package is 549 unknown or unsupported, then error code 518 should be used. 551 Category: "Provisioning Mismatch". 553 513 - gateway is not equipped to generate one of the requested 554 signals. 556 Response valid for: NotificationRequest. 558 Situation: A valid signal was requested, however the gateway is 559 not equipped to generate this signal (i.e., the package is only 560 implemented partially). Of course, such an implementation would 561 not conform to [1]. Note that if an invalid signal was 562 requested, i.e., a signal not defined in the relevant package, 563 then error code 522 should be used. Also note, that if the 564 package is unknown or unsupported, then error code 518 should be 565 used. 567 Category: "Provisioning Mismatch". 569 514 - The gateway cannot send the specified announcement. 571 Response valid for: NotificationRequest with a request for an 572 announcement to be played. 574 Situation: This is a specific situation with respect to 575 playing announcements on an endpoint or connection associated 576 with the endpoint. Error code 538 could be used instead. 578 Category: "Provisioning Mismatch". 580 MGCP Return Code Usage August 2003 582 515 - Incorrect connection-id. 584 Response valid for: CreateConnection, ModifyConnection, 585 DeleteConnection, NotificationRequest, AuditConnection. 587 Situation: An unknown connection-id has been specified. It is 588 possible that the connection has already been deleted. It should 589 be noted that a connection-id can also supplied with events and 590 signals (e.g., "S: L/rt@connId"). Note that a mismatch between 591 connection-id and call-id should use error code 516. 593 Category: "State Mismatch". 595 516 - Unknown or incorrect call-id. 597 Response valid for: ModifyConnection, DeleteConnection. 599 Situation: Unknown call-id, or the call-id supplied is 600 incorrect (e.g., connection-id not associated with this call- 601 id). 603 Category: "State Mismatch". 605 517 - Invalid or unsupported mode. 607 Response valid for: CreateConnection, ModifyConnection. 609 Situation: This is returned if the command specifies a 610 connection mode that the endpoint does not support (note that 611 not all endpoints will support all modes). Note that if the 612 unsupported mode is an extension connection mode, error code 518 613 (unsupported package) should be used instead. 615 Category: "Provisioning Mismatch". 617 518 - Unsupported or unknown package. 619 Response valid for: Any command 621 Situation: A package name included in a request is not 622 supported (or unknown). Note that the package name may be a 623 prefix to an event or other things (e.g. a parameter) as defined 624 in [1]. Note that it is recommended to include a PackageList 625 parameter with a list of supported packages in the response. 627 Category: "Provisioning Mismatch". 629 519 - Endpoint does not have a digit map. 631 Response valid for: NotificationRequest. 633 Situation: Request was made to detect digits based on a digit 634 map and the gateway does not have a digit map. 636 MGCP Return Code Usage August 2003 638 Category: "State Mismatch". The Call Agent needs to send down 639 a digit map in order to continue with the call. 641 520 - Endpoint is restarting. 643 Situation: This is normally a transient error in which error 644 code 405 SHOULD be used. Gateways SHOULD not use this error code 645 unless there is some relevant situation that warrants the 646 category of "Service Failure". Note that this was included in 647 [1] only to maintain backwards compatibility with previous 648 releases of the MGCP specification. 650 Category: If it is returned, this return code will be treated 651 as category "Service Failure", i.e., as if this endpoint is out- 652 of-service. 654 521 - Endpoint re-directed to another Call Agent. 656 Response valid for: RestartInProgress. 658 Situation: A RestartInProgress command was sent to the Call 659 Agent and the Call Agent returns this return code along with a 660 NotifiedEntity parameter pointing to another Call Agent. The 661 gateway then sends a new RestartInProgress command to the Call 662 Agent specified in the Notified Entity. 664 Category: none (specific situation and behavior). 666 522 - No such event or signal. 668 Response valid for: NotificationRequest. 670 Situation: This is returned if the requested event/signal name 671 is not registered with this package. If on the other hand the 672 signal or event is part of the package but is not supported by 673 the gateway, then return code 512 or 513 SHOULD be provided 674 instead. If the package is not supported, return code 518 SHOULD 675 be returned. 677 Category: "Provisioning Mismatch". 679 523 - Unknown action or illegal combination of actions. 681 Response valid for: NotificationRequest with one or more 682 requested events. 684 Situation: Request was made with a requested event(s) that 685 included an action or actions defined in [1] that are either 686 unknown, unsupported or an illegal combination as indicated in 687 section 2.3.3 of [1]. Note that unsupported extension actions 688 should generate error code 518 (unsupported package). 690 Category: "Provisioning Mismatch". 692 MGCP Return Code Usage August 2003 694 524 - Internal inconsistency in Local Connection Options 696 Response valid for: CreateConnection, ModifyConnection. 698 Situation: This is returned if one or more of the 699 LocalConnectionOptions (LCO) parameters are coded with values 700 that are not consistent with each other (e.g. other LCO 701 parameters inconsistent with the network type). 703 Category: "Provisioning Mismatch". 705 525 - Unknown extension in Local Connection Options. 707 Response valid for: CreateConnection, ModifyConnection. 709 Situation: This is returned if the request contains a Local 710 Connection Option with one or more unrecognized mandatory ("x+") 711 extensions. Note that unsupported package extensions should use 712 error code 518 (unsupported package) instead. 714 Category: "Provisioning Mismatch". 716 526 - Insufficient bandwidth 718 Response valid for: CreateConnection, ModifyConnection. 720 Situation: In most cases where there is insufficient 721 bandwidth, a 404 return code should be used. 526 would be used 722 in cases where future requests are destined to fail. An example 723 might be a very restricted bandwidth case, where there is not 724 enough bandwidth available for the codec requested even for a 725 single endpoint. Making a request with the same codec in the 726 future will fail. However, making a request for some other codec 727 (with a higher degree of compression) may pass. For cases, where 728 the bandwidth is pooled over multiple endpoints and could free 729 up at some future time (because an endpoint becomes inactive), 730 then 404 is more appropriate. 732 Category: If it is returned, this return code will be treated 733 as category "Provisioning Mismatch", e.g., the codec was 734 incorrectly provisioned for the bandwidth available. 736 527 - Missing RemoteConnectionDescriptor. 738 Response valid for: CreateConnection, ModifyConnection, 739 NotificationRequest. 741 Situation: This is returned if the connection has not yet 742 received a RemoteConnectionDescriptor when one is required to 743 support the request. This can for example happen if a connection 744 is attempted to be placed in "send/receive mode", or if a signal 745 is applied on a connection. 747 MGCP Return Code Usage August 2003 749 Category: "Remote Connection Descriptor Error" in the case 750 where the other end did not provide a connection descriptor. 751 Alternatively, if this is an initial request made by a Call 752 Agent (such there is no remote connection descriptor), then this 753 is a "State Mismatch" problem. 755 528 -Incompatible protocol version 757 Response valid for: Any command. 759 Situation: A command was received with a protocol version that 760 was not supported. 762 Category: "Provisioning Mismatch". This could also be treated 763 as a "State Mismatch" problem if the there is a recovery 764 mechanism (e.g. Call Agent recognizes the protocol version 765 mismatch and switches to the correct protocol version) 767 529 - Internal Hardware Error. 769 Response valid for: Any command. 771 Situation: A hardware fault occurred during the execution of a 772 command such that repeating this command will result in a 773 failure indication once again. This is a slightly more specific 774 error code than error 502, although more commentary should be 775 provided (for debug purposes) if possible. 777 Category: "Service Failure". 779 530 - CAS Signaling Protocol Error. 781 Response valid for: NotificationRequest. 783 Situation: This is specific to Channel Associated Signaling 784 (CAS) interfaces. A typical example might be an attempt to 785 outpulse digits failed for some reason. 787 Category: none (specific situation and behavior). 789 531 - Failure of a grouping of trunks (e.g. facility failure) 791 Response valid for: CreateConnection, ModifyConnection, 792 NotificationRequest. 794 Situation: Request made to an endpoint that has a failed trunk 795 connection (e.g. T1 or E1 failed). Note that an RSIP should have 796 been sent as a result of the facility failure. This is a more 797 specific response than return code 501. 799 Category: "Service Failure". 801 MGCP Return Code Usage August 2003 803 532 - Unsupported value(s) in Local Connection Options. 805 Response valid for: CreateConnection, ModifyConnection. 807 Situation: This is returned if one or more of the 808 LocalConnectionOptions parameters are coded with a value that 809 the gateway does not support. 811 Category: "Provisioning Mismatch". 813 533 - Response too large 815 Response valid for: Any command. 817 Situation: This would only be likely to occur in the case of an 818 audit where the maximum response packet size would end up being 819 too large. 821 Category: none (specific situation and behavior). 823 534 - Codec negotiation failure 825 Response valid for: CreateConnection, ModifyConnection. 827 Situation: The intersection between the list of codecs that 828 the gateway supports, the codecs allowed by the local connection 829 options and the codecs supplied in the Remote Connection 830 Descriptor (if provided) is empty. 832 Category: "Provisioning Mismatch" if the error resulted from 833 an empty approved list of codes as described in [1], Section 834 2.6). "Remote Connection Descriptor Error" if the error resulted 835 from an empty negotiated list of codecs, as described in [1], 836 Section 2.6. 838 535 - Packetization period not supported 840 Response valid for: CreateConnection, ModifyConnection. 842 Situation: Normally this error should not be generated since 843 if the gateway is unable to support the packetization period 844 specified in the local connection options for the codec 845 indicated, it should follow the behavior specified in [1] (which 846 is to pick an appropriate value rather than failing the 847 request). 849 Category: "none". 851 536 - Unknown or unsupported Restart Method 853 Response valid for: RestartInProgress. 855 Situation: This error is generated by the Call Agent if it 856 receives a RestartInProgress command with an unsupported restart 857 MGCP Return Code Usage August 2003 859 method. Note that if the restart method is an extension restart 860 method, error code 518 (unsupported package) should be used 861 instead. 863 Category: "Provisioning Mismatch". 865 537 - Unknown or unsupported digit map extension 867 Response valid for: NotificationRequest. 869 Situation: Digit map letter in the digit map unknown or 870 unsupported. Note that this code does apply to extension digit 871 map letters as well. 873 Category: "Provisioning Mismatch". 875 538 - Event/signal parameter error 877 Response valid for: NotificationRequest. 879 Situation: It is returned if the event/signal parameter is in 880 error or not supported. If the event/signal or a package is not 881 supported, then one of 512, 513, 518, or 522 should be used 882 instead. 884 Category: "Provisioning Mismatch". 886 539 - Invalid or unsupported command parameter 888 Response valid for: Any command. 890 Situation: This is returned if the command contains an invalid 891 or unsupported parameter, which is neither a package (which 892 would use return code 518) nor vendor specific extension (which 893 would use return code 511). For example, if an endpoint does not 894 support the BearerInformation parameter of the 895 EndpointConfiguration command, this return code could be used. 896 Of course, such an implementation would not conform to [1]. 898 Category: "Provisioning Mismatch". 900 540 - Per endpoint connection limit exceeded 902 Response valid for: CreateConnection. 904 Situation: A CreateConnection command was made, but the 905 gateway cannot support any additional connections on that 906 endpoint. 908 Category: "State Mismatch". 910 541 - Invalid or unsupported Local Connection Options 912 Response valid for: CreateConnection, ModifyConnection. 914 MGCP Return Code Usage August 2003 916 Situation: This is returned if the command contains an invalid 917 or unsupported LocalConnectionOption, which is neither a package 918 (which would use return code 518) nor vendor specific extension 919 (which would use return code 511). 921 Category: "Provisioning Mismatch". 923 2.3. Summary of Return Code Categories 925 A summary of the categories of the various error codes is included in 926 the following table. This information is also repeated in the 927 detailed error descriptions in the next section. 929 ------------------------------------------------------------------ 930 | Category | Return Codes | 931 |-------------|----------------------------------------------------| 932 | normal | 000, 100, 101, 200, 250 | 933 |-------------|----------------------------------------------------| 934 | none | 405, 407, 410, 510, 521, 530, 533, 535 | 935 |-------------|----------------------------------------------------| 936 | "Service | 501, 502, 520, 529, 531 | 937 | Failure" | | 938 |-------------|----------------------------------------------------| 939 |"Provisioning| 500, 503*, 504, 507, 508, 510, 511, 512, 513, 514, | 940 | Mismatch" | 517, 518, 522, 523, 524, 525, 526, 528*, 532, 534*,| 941 | | 536, 537, 538, 539, 541 | 942 |-------------|----------------------------------------------------| 943 | "Temporary | 400, 403, 404*, 405, 406, 409 | 944 | Failure" | | 945 |-------------|----------------------------------------------------| 946 | "State | 401, 402, 515, 516, 519, 540 | 947 | Mismatch" | | 948 |-------------|----------------------------------------------------| 949 | "Remote | 505, 506, 509, 527* | 950 | Connection | | 951 | Descriptor | | 952 | Error" | | 953 ------------------------------------------------------------------ 955 Notes: 956 * 404: may be treated as a "Temporary Failure", but specific 957 behavior is possible (e.g. trying an alternate codec with lower 958 bandwidth requirement rather than failing this call). 960 * 503: rather than treating this as a "Provisioning Mismatch", it 961 is possible for the Call Agent to recover from this error. 963 * 527: See the detailed description for this error code in section 964 2.2. This could be treated as a "State Mismatch" depending on 965 the circumstances. 967 MGCP Return Code Usage August 2003 969 * 528: See the detailed description for this error code in section 970 2.2. This could be treated as a "State Mismatch" depending on 971 the circumstances. 973 * 534: See the note on error code 534 in the detailed description 974 section (2.2) of this document (may be treated as a "Remote 975 Connection Descriptor Error" if no local connection options were 976 supplied). 978 3.0. Additional Guidelines 980 This section provides additional guidelines to Gateway and Call Agent 981 developers. 983 3.1. Gateway Recommendations 985 The following guidelines are recommended for gateway implementations: 987 * For uncategorized return codes (category "none") that involve 988 specific situations, gateways should make sure they do an 989 accurate mapping between the situation and the return code. 990 * Also for category "State Mismatch", it is equally important that 991 the situation (and state) is accurately mapped to the specific 992 error code. 993 * For situations similar to those involving return codes in 994 "Service Failure", Provisioning Mismatch", "Temporary Failure" 995 and "Remote Connection Descriptor Error" categories, the gateway 996 should make sure that it uses a return code in the correct 997 category. 998 * MGCP allows additional commentary to be included with the return 999 code. It is important that the gateway includes more specific 1000 information concerning the situation for debug purposes. 1001 * It is recommended that return codes 502, 520 and 526 not be used 1002 unless there is something that makes these permanent situations. 1003 As indicated in the detailed description of these return codes, 1004 403, 405 and 404 respectively are more appropriate in almost all 1005 situations. If a gateway presently uses 502, 520 and 526 for 1006 temporary situations and expects to upgrade to 403, 405 and 404, 1007 the gateway should refrain from using 502, 520 and 526 for some 1008 other use immediately after the upgrade. This is to avoid 1009 problems where a Call Agent is expected to treat the same error 1010 code in two different ways, e.g., 403 is a category "Temporary 1011 Failure" which requires a different Call Agent behavior from 502 1012 which is in category "Service Failure". 1014 3.2. Call Agent Recommendations 1016 The following guidelines are recommended for gateway implementations: 1018 * Call Agents should handle return codes they do not recognize (or 1019 do not expect) based on the first digit in the return code as 1020 outlined in [1]. 1021 * For categories "Service Failure", "Provisioning Mismatch", 1022 "Temporary Failure", and "Remote Connection Descriptor Error", 1023 MGCP Return Code Usage August 2003 1025 Call Agents are expected to treat return codes that are within 1026 the same category in the same way (i.e., make the same decision, 1027 based on the return code and other state information available 1028 to them). 1029 * Because there was little guidance given for return codes 502, 1030 520 and 526 in RFC 2705, Call Agents may have to treat these as 1031 403, 405 and 404 respectively for gateways that have not been 1032 updated according to [1] and these recommendations. The gateway 1033 implementer should be consulted for information on the gateway 1034 behavior for (now and in the future) for these return codes 1035 (i.e., it may be that return codes 502, 520 and 526 are 1036 presently used incorrectly but will be replaced with 403, 405 1037 and 404 in the future). 1039 4.0. Security Considerations 1041 This document merely provides a convenient way to categorize MGCP 1042 return codes in order to facilitate decisions related to failure 1043 conditions; it does not impact MGCP security in any way. 1045 5.0. Acknowledgements 1047 Thanks also to Kevin Miller, Joe Stone, Flemming Andreasen, Bob 1048 Biskner for input contributions used in this document. 1050 6.0. References 1052 [1] Andreasen and Foster, Media Gateway Control Protocol (MGCP) 1053 Version 1.0, RFC 3435, January 2003 1054 [2] Foster and Andreasen, Basic MGCP Packages, [editors note: to be 1055 provided with RFC number when available for draft-foster-mgcp- 1056 basic-packages-10.txt]. 1057 [3] Handley, M. and V. Jacobson, SDP: Session Description Protocol, 1058 RFC 2327, April 1998. 1060 7.0. Authors' Addresses 1062 C. Sivachelvan 1063 Cisco Systems 1064 2200 East President George Bush Turnpike 1065 Richardson, TX, 75082 1066 chelliah@cisco.com 1068 B. Foster 1069 Cisco Systems 1070 bfoster@cisco.com 1071 MGCP Return Code Usage August 2003 1073 8.0. Full Copyright Statement 1075 Copyright (C) The Internet Society (2003). All Rights Reserved. 1077 This document and translations of it may be copied and furnished to 1078 others, and derivative works that comment on or otherwise explain it 1079 or assist in its implementation may be prepared, copied, published 1080 and distributed, in whole or in part, without restriction of any 1081 kind, provided that the above copyright notice and this paragraph are 1082 included on all such copies and derivative works. However, this 1083 document itself may not be modified in any way, such as by removing 1084 the copyright notice or references to the Internet Society or other 1085 Internet organizations, except as needed for the purpose of 1086 developing Internet standards in which case the procedures for 1087 copyrights defined in the Internet Standards process must be 1088 followed, or as required to translate it into languages other than 1089 English. 1091 The limited permissions granted above are perpetual and will not be 1092 revoked by the Internet Society or its successors or assigns. 1094 This document and the information contained herein is provided on an 1095 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 1096 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 1097 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 1098 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 1099 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1101 Acknowledgement 1103 Funding for the RFC Editor function is currently provided by the 1104 Internet Society.