Subject: Re: Errors and Error Codes

From: "Rupsis, Paul" <[email-masked]>
Date: Fri, 11 Feb 2000 12:37:59 -0500

> C. Errors Defined In Packages
>
> We agreed with the Cisco proposal that it be possible to define error
codes
> in packages.  This would just be a matter of documentation convenience --
> the codes would NOT be qualified by package name, and the package
> documentation would serve double duty as far as IANA registration is
> concerned.  IMHO this means no change to our existing section 12 except
> perhaps to mention this possibility in the packages section.  Assignment
of
> codes would follow the usual rules: 000-999 range for ITU/IETF codes, 1000
> -9999 for private packages.

Granted, 10,000 error codes are a lot, but across how many packages?
What is the downside of qualifying error codes by package name thus
guaranteeing that each package developer has an available, known, and
fixed error code space prior to IANA registration?

Otherwise, I foresee packages being defined with alternative approaches to
returning errors. For example, the advanced audio package submission,
draft-cromwell-megaco-advanced-audio-pkg-00.txt, didn't define any error
codes but created an Audio Operation Failed event with a return code
as a parameter in the ObservedEvents Descriptor.

Error detection can always be defined as an event within a package.

Paul Rupsis
Dialogic, an Intel Company

-----Original Message-----
From: Tom-PT Taylor [mailto:[email-masked]]
Sent: Friday, February 11, 2000 6:41 AM
To: [email-masked]
Subject: Errors and Error Codes

This E-mail covers several topics dealing with error reporting.

A. Asynchronous Error Reporting
========================

We have discussed, here in Geneva, a mechanism for generating spontaneous
notifications of error conditions (i.e. use of the "cause" event in the
generic package).  The suggested mechanism is this:

  -- we reserve a block of event request-IDs (e.g. 0-15) for assignment to
classes of event the MGC will always want enabled (or alternatively can
enable or disable using a Root property).  As an example of use, we assign
requestID 0 to spontaneous error reports.  This way it won't be necessary to
include the cause event in every Event Descriptor

  -- rather than making errorDescriptor an optional component of the Notify
command (as our ABNF now states), we make it a parameter of the cause event.

  -- this mechanism allows the inclusion of some error codes in our list in
section 7.3 which otherwise shouldn't be there because they would not result
from transaction processing.  One example is 518 "event buffer full".

B. Errors In Transaction Reply

I'm not sure we have a procedure for handling errors in Transaction Reply.
Unless someone can point me to the existing text, we should add something to
cover the situation.

D. Review Of Error Codes

I have reviewed the error codes in the current document, and have compiled
explanations for a number of them.  Others I can't explain, and suspect they
shouldn't be there.  I would like other people to review my findings so we
can get this straightened out.  In what follows, errors marked with an
asterisk could be returned against transaction replies as well as
transaction requests.  My comments are enclosed in square brackets.  I
present no explanations for error codes which seem to be adequately
described by the text shown against them in 7.3.

Could someone explain the logic behind the assignment of these codes?  Why
start at 400? -- our numbering space is only 000 to 999 and it doesn't seem
right to waste half of it.

*400 - Bad Request
        A syntax error has been detected at the message level.  The message
does not conform to the productions MegacoMessage or Message in Annex A or
Annex B as applicable.

*401 - Protocol Error
        A violation of Megaco protocol procedures has been detected.  Use
error codes corresponding to more specific conditions if they apply.  [e.g.
465, 466, 467 if they turn out to be justified; 505, 521.]

402 - Unauthorized
        The originator of a command is not authorized to execute that
command for the termination(s) affected by it.  [For messages failing
authentication, what is our procedure? ]

403 - Syntax Error in Transaction
        The form of a transaction request failed to match production
transactionRequest in Annex A, Annex B, or section D.1.2 of Annex D as
applicable.  [Note: review codes proposed in sec. 8.2.2.]

*404 - Syntax Error in TransactionReply
        The form of a transaction reply failed to match production
transactionReply in Annex A, Annex B, or section D.1.2 of Annex D as
applicable.

*405 - Syntax Error in TransactionPending
        The form of a transaction pending failed to match production
transactionPending in Annex A, Annex B, or section D.1.2 of Annex D as
applicable.

*406 - Version Not Supported
        Used by the receiver of a transaction request to indicate lack of
support for the protocol version indicated in the message header.  [Note
usage in sec. 11.3 -- I think there is an error in the second para last
sentence (should be MG, not MGC)]

*410 - Incorrect identifier
        A syntax error has been found in an mId, transactionId, contextId,
terminationId, PropertyId, EventId, SignalId, StatisticsId or ParameterId.

411 - The transaction refers to an unknown ContextId
        A specific contextID provided in a Transaction Request is unknown to
the respondent.  For unknown contextID in Transaction Reply use error code
46x "ContextIDs in Reply do not match Request" [which isn't currently
defined -- could change 461].

412 - No ContextIDs available
        The MG is unable to create a new context in response to an Add or
Move command with CHOOSE given as the contextId, because of a shortage of
software or hardware resources within the MG.

421 - Unknown action or illegal combination of actions
        [Can't happen -- actions don't have tags or semantics in
themselves.]

*422 - Syntax Error in Action
        The syntax of an Action did not conform to production actionRequest
or actionReply as applicable.  Use error code 405 or 406 as applicable if
parsing failed to delineate the end of the Action.
        [Check usage in 8.2.2]

430 - Unknown TerminationID
        A specific terminationID provided in a Transaction Request is
unknown to the responder.  For unknow terminationIDs in Transaction Replies
use error code 463.

431 - No TerminationID matched a wildcard
         The Transaction Request specified a TerminationID including both
specific content and one or more wildcards (ALL or CHOOSE), but the
responder could not find an existing termination or, because of internal
naming constraints, create a new termination matching the specified pattern.

432 - Out of TerminationIDs or No TerminationID available
        The MG was unable to allocate a new terminationID in response to an
Add command specifying a CHOOSE termination identifier, because it has
exhausted the applicable local name space or some other per-termination
resource.

433 - TerminationID is already in a Context
        A TerminationID specified in an Add command already exists within an
active context.

440 - Unsupported or unknown Package
        The package named in a Property, Event, Signal, or Statistic
identifier is not supported by the respondent.

441 - Missing RemoteDescriptor
        The MGC has attempted to set the Mode of a stream on a termination
to SendOnly or SendReceive but an inadeqate or no outgoing media
specification has been provided in a Remote Descriptor for that stream.
[Note: same thing can apply to Local/incoming flows.  Generalize this error
to "Attempt to activate underspecified flow"?]

*442 - Syntax Error in Command
        A command request has failed to match the syntax of the
commandRequest production, or a command reply in a transaction response has
failed to match the syntax of the CommandReply (Annex A) or commandReplys
(Annex B) production, as applicable. Use the 422 error code if parsing
failed to delineate the end of the command request or command reply.  [Check
use in sec. 8.2.2.]

443 - Unsupported or Unknown Command
        The respondent to a Transaction Request successfully parsed a
command to the point of delineating the command type, but does not recognize
or support the command type.  Use the 442 error code if the respondent
failed to delineate the command type.

*444 - Unsupported or Unknown Descriptor
        A  command request or command reply was successfully parsed to the
point of delineating the type of a descriptor, but the descriptor type is
not recognized or supported.  The 442 error code should be used if parsing
failed to delineate the end of the descriptor, the descriptor type, or
individual properties, parameters, or values within the descriptor.

*445 - Unsupported or Unknown Property
        [Redundant -- use 450]

*446 - Unsupported or Unknown Parameter

*447 - Descriptor not legal in this command

*448 - Descriptor appears twice in a command

*450 - No such property in this package
        The Property Name (Annex A) or ItemID (Annex B) of a property within
a descriptor is either unsupported or unrecognized.  Use error code 440 if
the Package Name associated with the property is unrecognized.

*451 - No such event in this package
        This could apply to a reply for the AuditValue command as well as
the more common case of faulty EventDescriptors in other commands.  Use
error code 440 if the Package Name associated with the event is
unrecognized.

*452 - No such signal in this package
        This could apply to a reply for the AuditValue command as well as
the more common case of faulty SignalsDescriptors in other commands.  Use
error code 440 if the Package Name associated with the signal is
unrecognized.

*453 - No such statistic in this package
        Use error code 440 if the Package Name associated with the statistic
is unrecognized.

*454 - No such parameter value in this package
        The value given for a parameter is not legal for the package to
which the parameter belongs.  Use error code 450 if the type as opposed to
the value of the parameter is illegal.

*455 - Parameter illegal in this Descriptor

*456 - Parameter or Property appears twice in this Descriptor

*461 - TransactionIDs in Reply do not match Request
[Can't be detected.  Should be ContextIDs rather than TransactionIDs.  See
comment on 411]

*462 - Commands in Transaction Reply do not match commands in request

*463 - TerminationID of Transaction Reply does not match  request
[Should be phrased similarly to 462]

*464 - Missing reply in Transaction Reply
        [Assuming 461 is changed to ContextIDs and given 462, this one is
redundant]

*465 - TransactionID in Transaction Pending does not match any open request
[Unusable -- contrary to procedures in D.1.4]

466 - Illegal Duplicate Transaction Request
[Unusable -- contrary to procedures in 8.2.3]

*467 - Illegal Duplicate Transaction Reply
[Unusable -- contrary to Annex D procedures?]

471 - Implied Add for Multiplex failure
        A termination listed within a multiplex descriptor could not be
added to the current context.  If the reason is because the termination is
already in a different active context, use error code 433.

500 - Internal Gateway Error
        A command could not be executed properly due to a software failure
within the MG.  For hardware failures, see error code 529.

501 - Not Implemented
        [Redundant??? (Codes 443-446)]

502 - Not ready
        The respondent is temporarily unable to process requests because of
its own internal state.

503 - Service Unavailable
        [What service???  Likely conditions are covered by other error
codes]

504 - Command Received from unauthorized entity
        [Redundant -- covered by 402?]

505 - Command Received before Restart Response
        Issued by the MG which has issued a ServiceChange request to an MGC
if it receives a transaction request from that MGC before it has processed
the response to the ServiceChange request.  See procedural notes in section
11.2.

510 - Insufficient resources
        The MG is unable to execute a command because of a lack of resources
within the MG.

512 - Media Gateway unequipped to detect requested Event
        Self-descriptive.  If the MG does not support the package in which
the event is specified, use code 440.

513 - Media Gateway unequipped to generate requested Signals
        Self-descriptive.  If the MG does not support the package in which
the signal is specified, use code 440.

514 - Media Gateway cannot send the specified announcement
        [Package specific -- should be documented in the announcement
package]

515 - Unsupported Media Type
        [Might want to make it "Unsupported media type or media conversion"
]

517 - Unsupported or invalid mode
        [Too detailed.  Need a general "Unsupported or invalid value" }

518 - Event buffer full
        Reported via the Notify command using the Cause event in the Generic
package.  See procedures in section 7.2.7 [to be added as noted at the start
of this E-mail]

519 - Out of space to store digit map

520 - Media Gateway does not have a digit map
        The digit map named in a command is not specified.  [Probably want
to change to "Digit Map undefined"]

521 - Termination is "ServiceChangeing"
        [Inapplicable if we get rid of Graceful ServiceChange for
terminations.]

526 - Insufficient bandwidth
        The MG was unable to execute a command because of insufficient
resources at the network interface or externally to the MG.

529 - Internal hardware failure
        A command could not be executed properly due to a hardware failure
within the MG.

530 - Temporary Network failure
        The MG was unable to execute a command because of a network failure
of unspecified but temporary nature affecting the termination concerned.  If
the failure renders an existing termination unavailable for service, the MG
should follow up by issuing a ServiceChange on the termination to indicate
its unavailability.

531 - Permanent Network failure
        The MG was unable to execute a command because of a network failure
of unspecified and persistent nature affecting the termination concerned.
If the failure renders an existing termination unavailable for service, the
MG should follow up by issuing a ServiceChange on the termination to
indicate its unavailability.

581 - Does Not Exist
        [Covered by more specific errors (e.g. 411, 430)]

Tom Taylor
Advisor -- Emerging Carrier IP Standards
E-mail: [email-masked] (internally, Tom-PT Taylor)
Phone and FAX: +1 613 736 0961

---

From: Tom-PT Taylor <[email-masked]>
Date: Sat, 12 Feb 2000 15:56:30 -0600

Thanks for your review.  I've deleted the stuff we agree on to make my
comments clearer.

> From: Christian Groves [SMTP:[email-masked]]
> Sent: Friday, February 11, 2000 1:06 PM
        [[TomT]]  ...
> [CHG] Do we really need this? Doesn't it depend on the application
>       what it wants to do when it encounters an error?
        [[TomT]]
        You could make the same argument for the responder reaction to
errors in transaction requests.  "It's an application issue how to respond
to errors."   I don't buy that -- the protocol requires some standardized
means of communicating a failure to communicate.

> [CHG] We have not agreed on this at the ITU meeting and is still under
> discussion.
>  How this works with regards to package extension and versioning is
> still an open issue.
        [[TomT]]
        The key point here is that IANA must have a pointer to the latest
documentation.

> > D. Review Of Error Codes
        [[TomT]]  ...  In what follows, errors marked with an
> > transaction requests. [[TomT]]  ...
>  [CHG] Do we need to mark directions with a '*'. It should be obvious.
        [[TomT]]
        That's only for convenience of review.  It reinforces my point that
there has to be some protocol means to indicate a failure in a reply -- many
of these asterisked items could not be transmitted otherwise.

> [CHG1] Leave out references to D.1.2 as this might not be supported
> depending on transport. transactionRequest in Annex A and B should cover
> things.
        [[TomT]]  OK for this, 404, 405

> [CHG] Valid for ServiceChange perhaps text should be:
> "Used by receiver to indicate lack of support for the protocol version."
        [[TomT]]  See your point.  How about: "Used by the receiver of a
message to indicate lack of support for the protocol version in the message
header.  Also used by the MG to indicate its lack of support for the
protocol version in the ServiceChangeVersion of a ServiceChange response."

> [CHG]+  The MG is unable to create a new context in because of a
> shortage of
> [CHG]+ software or hardware resources within the MG.
        [[TomT]]  OK, minus the redundant "in"

> > responder could not find an existing termination <Delete>>>or, because
> of internal
> > naming constraints, create a new termination matching the specified
> pattern.>
> [CHG] Remove create comment.
        [[TomT]]  OK

> [CHG] How about?
> "The MG was unable to allocate a new terminationID."
        [[TomT]]  How about the same phrasing as for contextID:
        "The MG is unable to create a new terminationID because of a
        shortage of software or hardware resources within the MG."

> [CHG] Is this really needed at all? if you try to modify Mode without a
> Remote/LocalDescriptor isn't it a syntax error?
        [[TomT]]  No it isn't -- Mode is in LocalControl

> [CHG] This is valid. Annex C would use this. I gather SDP has properties
> (attributes)
        [[TomT]]  But they would be defined in packages.  It seems to me the
answer is to make sure that disjoint sets of Annex C properties are
allocated different package numbers.
> [CHG] OK
> [CHG] Perhaps this should be???
>     501 - Unsupported property value
> May need also:
>     50x - Unknown property value
>
> >
        [[TomT]]   517 or 501, doesn't matter
> [CHG] This should stay.
        [[TomT]]  Have to see what comes out of the "test" discussion
> > of unspecified but temporary nature affecting the termination concerned.
>
> > [Delete>>>> If
> > its unavailability.  <<<<<]
> [CHG] Remove advisory text. Up to MGC.
        [[TomT]]  No.  If our protocol has any meaning, it's the MG that has
to make the report.  It is actually implementation-dependent whether the
ServiceChange would precede or follow this error reply, so I should change
the wording to that extent..
> [CHG] Delete>>>>>
> > indicate its unavailability.<<<<<<
        [[TomT]]  Same comment as above.

---

From: Tom-PT Taylor <[email-masked]>
Date: Sat, 12 Feb 2000 16:07:58 -0600

Thanks for your comments.

> From: Chuong Nguyen [SMTP:[email-masked]]
> Sent: Friday, February 11, 2000 1:54 PM
> Subject:      Re: Errors and Error Codes
>
>       >
> Tom , are you trying to say that the text does not talk about responsing
> to a Transaction Reply
> or Transaction Pending?
> Are we supposed to response to Transaction Reply and Transaction Pending.
> If no, we do not need all the error codes related to Transaction Reply and
> Transaction Pending.
> If yes, then are we going to have syntax error code for the responses to
> the Transaction Reply
> and Transaction Pending.  This could go on and on...
        [[TomT]]  Well, we certainly wouldn't want that.  It may be the
right answer is that errors in responses are ignored.  As I said in my note
to Christian, that will cut down on the error code list.  Alternatively we
have to have some message type to which responses are forbidden.

> I don't know about replying to authentication failure.  This would just
> help an attack on MG or MGC
> by making it responses to this message.
        [[TomT]]  My thought too.

        [[TomT]]  ...
> except for error descriptor???
        [[TomT]]  Good point -- have to add that

> Is this for trying to Add, modify a termination that is out of service?
        [[TomT]]  Don't think so as it is phrased, but we probably should
rephrase to cover that case.  We figured out here that it has to be possible
to modify an out of service termination so that it can be put into a test
state for running tests prior to restoration.
> Are there talk about getting rid of Graceful ServiceChange for
> terminations?
> The text said that the termination service state is changed from
> in-service to test while being
> ServiceChange w/Graceful.
> Can we line this 2 up with one phrase - ServiceChanging or test?
        [[TomT]]
        Still sorting it out.  Must get the whole story out -- maybe
tomorrow morning.

---

From: Tom-PT Taylor <[email-masked]>
Date: Sat, 12 Feb 2000 16:12:41 -0600

Thanks for the history -- I suspected as much.  There was a small debate on
the list around a Cisco point, rerquesting return codes rather than error
codes.  The consensus as I see it is that Megaco passes error codes only --
the general response mechanism is defined by the syntax of Transaction
Reply.  Hence it is more appropriate to use the full numbering space
starting from 000.

> From: Rayhan, Abdallah [CAR:5N00:EXCH]
> Sent: Friday, February 11, 2000 4:38 PM
> "Taylor, Tom-PT (P.T.) [EXCHANGE:CAR:B904]" wrote:
>
> Very well! It is an error reporting de facto that is used in several
> protocols.
> The only documentation I am aware of is reported in HTTP1.1 RFC 2616.
> I dont know where else or the origin but here is the documentation,
>
>
>       The first digit of the Status-Code defines the class of response.
> The
>       last two digits do not have any categorization role. There are 5
>       values for the first digit:
>
>             - 1xx: Informational - Request received, continuing process
>
>             - 2xx: Success - The action was successfully received,
>               understood, and accepted
>
>             - 3xx: Redirection - Further action must be taken in order to
>               complete the request
>
>             - 4xx: Client Error - The request contains bad syntax or
> cannot
>               be fulfilled
>
>             - 5xx: Server Error - The server failed to fulfill an
> apparently
>               valid request
>
> Hope that helps,
>
> Abdallah

---

From: Tom-PT Taylor <[email-masked]>
Date: Tue, 15 Feb 2000 03:17:38 -0600

Actually, this initiative died still-born, due to my stubbornness: I don't
believe the existing Cause event (which looks like a Q.2931 return code) is
sufficiently general for our needs.  What has happened is this: requestID 0
is reserved, with use for further study, and the errorDescriptor is an
optional part of the Notify in both ASN.1 and ABNF (was inconsistent
before).

My error code documentation wasn't picked up due to an opposing view that it
was only advice to implementors.  Given the number of questions we get about
this sort of thing, I propose to issue a separate I-D with definitive text
describing the error codes.  We can turn this into an RFC and it will be
available for people to refer to.  On the matter of error responses to
Transaction Reply, the general opinion was that that was too risky -- hence
related error codes should be deprecated or deleted.

> From: Flemming Andreasen [SMTP:[email-masked]]
> Sent: Monday, February 14, 2000 6:07 AM
> To:   Taylor, Tom-PT [CAR:B904:EXCH]
> Cc:   [email-masked]
> Hi Tom
> Thanks for the clarifications - now I have some comments below.
>
>
> Tom-PT Taylor wrote:
>
>
>
>       Replies below.
>
>       From:   Flemming Andreasen [SMTP:[email-masked]]
>       Sent:   Friday, February 11, 2000 9:29 AM
>       To:     Taylor, Tom-PT [CAR:B904:EXCH]
>       Cc:     [email-masked]
>               Tom-PT Taylor wrote:
>               I agree with the goal, but I'm not sure I agree with the
> solution (could be I
>       just misinterpreted it), so let me ask a couple of questions for
> clarification:
>
>               Does this mean, that if I play a signal that succeeds, I
> will get a completion
>       event through the normal channels and with a RequestID matching my
> request, but
>       if it fails, it will come through this other channel using one of
> these special
>       RequestIDs ?
>       [[TomT]]
>       That's correct.  Mind, if the completion event is left as it is now
> defined in -megaco-protocol-06, you will ALSO get a signal completion
> event with RequestID matching the request and termination method "FL".
> This can be changed -- it was due to be taken out in the wake of
> discussion on the list indicating a preference for using the Cause event.
>
> I would rather leave it the way it is as the above alternative is a recipe
> for race conditions. If I understand correctly, you are simply trying to
> optimize the flows by not requiring certain events to always be included
> in the EventsDescriptor. I can't think of a reason why you would want to
> report these differently than all other events. Seems like a recipe for
> race conditions to me.
>
>
>
>       What about ordering ? Will I be guaranteed to receive the error
> before any other
>       subsequent events on the termination ?
>       [[TomT]]
>       Somewhere -- presumably in the Events section -- we should state
> that the MG must report events in the order in which they occur.  Does
> this meet your requirement?
>
> Yes it does, but if you start reporting through different channels with a
> couple of reserved and "special" RequestIDs then you start complicating
> things. Ensuring ordered delivery here seems unnecessarily complicated and
> could easily cause a serious synchronization penalty which you would not
> have to deal with if you used the normal event reporting channels.
> It seems like you are effectively implementing SNMP traps although it's
> not clear how the MGC can actually control which of these "persistent"
> events it actually wants to hear about.
>
>
>
>
>               >
>               <<stuff deleted>>
>               -- Flemming
>               --
>       ---------------------------------------
>       Flemming Andreasen
>       Cisco Systems
>       ---------------------------------------
>
>
>
> -- Flemming
>
> ---------------------------------------
> Flemming Andreasen
> Cisco Systems
> ---------------------------------------
>