Error responses returned by implementation platforms e.g. Cloud and WAF

[ToshiWakayama-KDDI]

Dear CAMARA API specialist,

I have received a question from my API implementation team. The API design guidlines and each API specifications specify HTTP error responses. But, what about other errors, which will be returned to the API Client side by the cloud platforms (e.g. AWS, Google Cloud) and other equipment e.g. WAF (Web Application Firewall)?

Is it correct understanding that those kind of errors are not covered by the API Design Guidelines and the API specifications, so they are out of the CAMARA scope and CAMARA does not care?

Thank you,
Toshi

[eric-murray]

@ToshiWakayama-KDDI
Can you clarify why the API consumer would see error messages from these other platforms?

Is it because, for example, you are using AWS or Google Cloud implementations of API gateways or authorisation servers and are unable or do not want to customise their error messages to comply with CAMARA guidelines?

Or are there error conditions arising that fall outside of the scope of CAMARA?

[ToshiWakayama-KDDI]

Hi @eric-murray ,

Thank you so much for your answer and asking clarification. Actually there are both cases. We are unable to customise some errors and do not want to customise some, and for some errors, there are error conditions that we think fall outside of the scope of CAMARA?

Considering your answer, maybe we should customise API gateways' or auth servers' errors to comply with CAMARA guidelines, I feel. What about other cases, i.e. error conditions falling outside of the scope of CAMARA?

Many thanks,
Toshi

[eric-murray]

Hi @ToshiWakayama-KDDI

Generally, any CAMARA service API call resulting in an error should return a CAMARA compliant error message. However, there are a number of considerations:

• For some HTTP errors it is only really the status code that matters (e.g. 429 TOO MANY REQUESTS). So there will be errors where (generally) the error format doesn't matter, and CAMARA compliance is not really needed.
• Protocols operating below HTTP will obviously not return an HTTP error, and hence not return a CAMARA error. For example, if the API provider's TLS certificate has expired, then the error will be a TLS error, not a CAMARA error. API client implementations should always be ready for these lower level protocol errors.

For the authorisation / authentication stages, CAMARA follows OIDC, and I'm not aware that any custom errors have been defined for these steps. So implementations should follow OIDC standards regarding errors.

[ToshiWakayama-KDDI]

Thank you so much, @eric-murray , for your suppport. I am getting familiar with CAMARA errors, which is needed for our API implementation.

May I ask another question, please? If an API provider's system returns some error responses that are not compliant with CAMARA or not specified in CAMARA specs, what are API client apps supposed to do in geneneral? Are they supposed to just neglect unknown responses? Or, are they going to go wrong?

Many thanks,
Toshi

[eric-murray]

Well, this might break the client implementation, depending upon how tolerant (or otherwise) it is of non-standard error responses. In general, client implementations should not be overly strict on error formats if that has no effect on their handling of errors (for example, if the client just terminates on error, the error format itself doesn't really matter). But API providers will generally have no control over actual client implementations (though some will likely make SDKs available).

Initially, I'd expect many API providers to expose their APIs through an aggregator, and so the "client" for many implementations will be that aggregator. In that case, any non-compliance should be discussed with the aggregator, who may be able to adapt their implementations whilst maintaining CAMARA compliance for their own northbound APIs.