Api: Question about GetProfile parameters

[brandonmanke]

I apologize if this question has already been answered, but I don't seem to know why I am getting this invalid parameter error. My request path is /Platform/Destiny2/1/Profile/4611686018452936098/ and the error message is:

{ ErrorCode: 18,
  ThrottleSeconds: 0,
  ErrorStatus: 'InvalidParameters',
  Message: 'The input parameters were invalid, please enter valid input, and try again.',
  MessageData: {} }

The only thing I can think of is that for some reason I am not using the correct membershipId, but when I use SearchDestinyPlayer it returns this exact membershipId and type.

[vthornheart-bng]

Ah, so the problem here is almost certainly because we currently require at least one component identifier to be passed (the "?components=" querystring parameter). Unfortunately, this is an extremely misleading response code... I'll make this a bug because I'd like it to at least return which parameter it was expecting to receive that was invalid, and why it was invalid. In most spots in our API right now, InvalidParameters doesn't give nearly enough information.

[floatingatoll]

As a temporary measure, changing "The input parameters were invalid" to
"The URL's query parameters were missing or invalid" would go a long ways
to helping with that.

On Tue, Oct 24, 2017 at 10:27 AM, Vendal Thornheart <
[email protected]> wrote:

Ah, so the problem here is almost certainly because we currently require
at least one component identifier to be passed (the "?components="
querystring parameter). Unfortunately, this is an extremely misleading
response code... I'll make this a bug because I'd like it to at least
return which parameter it was expecting to receive that was invalid,
and why it was invalid. In most spots in our API right now,
InvalidParameters doesn't give nearly enough information.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
https://github.com/Bungie-net/api/issues/257#issuecomment-339068472, or mute
the thread
https://github.com/notifications/unsubscribe-auth/AAFqDIu3kNKMWO-h4UH5E1guL3hbRO9Dks5svh4CgaJpZM4QEtsV
.

[vthornheart-bng]

Yeah, as a stopgap I wouldn't be opposed to changing it to something like that - but I don't know if it'd help a lot in this case, because I think the core problem is that we leave you to guess which parameter it is that failed and why.

[floatingatoll]

What's the link to ErrorCode 18's documentation?

On Tue, Oct 24, 2017 at 10:36 AM, Vendal Thornheart <
[email protected]> wrote:

Yeah, as a stopgap I wouldn't be opposed to changing it to something like
that - but I don't know if it'd help a lot in this case, because I think
the core problem is that we leave you to guess which parameter it is that
failed and why.

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
https://github.com/Bungie-net/api/issues/257#issuecomment-339071207, or mute
the thread
https://github.com/notifications/unsubscribe-auth/AAFqDAI8-XEXvxo5nsP3hv-fJ-Lrtbyiks5sviAagaJpZM4QEtsV
.

[vthornheart-bng]

For most of the codes, we don't actually have any documentation written (yet). They're all found under:

https://bungie-net.github.io/multi/schema_Exceptions-PlatformErrorCodes.html#schema_Exceptions-PlatformErrorCodes

[floatingatoll]

I encourage you to add a new JSON property to error responses:

'ErrorDocumentation': 'https://...#ErrorCode18'

That directly links to the errorcode #18 explanation, whether or not it
exists yet. That way developers know where to look, but users (who see the
Message property) aren't bothered with an extra hundred characters of URL.

On Tue, Oct 24, 2017 at 10:43 AM, Vendal Thornheart <
[email protected]> wrote:

For most of the codes, we don't actually have any documentation written
(yet). They're all found under:

https://bungie-net.github.io/multi/schema_Exceptions-
PlatformErrorCodes.html#schema_Exceptions-PlatformErrorCodes

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
https://github.com/Bungie-net/api/issues/257#issuecomment-339073366, or mute
the thread
https://github.com/notifications/unsubscribe-auth/AAFqDMY4wfLLQvQ4trDy62MTjE97JfaFks5sviHSgaJpZM4QEtsV
.

[vthornheart-bng]

I don't know - we'd have to ask ourselves how far we take something like that and how useful it'd actually be to someone. If we start adding documentation links for that, what makes error code documentation more important than, say, adding a link to the documentation for some result property that's hard to understand? And ideally, if people wanted to know what the result codes were, they could look up the API docs for the method that they were calling and they should see the link to the result codes right there in the docs (as is the case for other properties that we return). The only people who couldn't do that would be people who don't know the docs exist at all: but at that point, I think adding a documentation link specifically for the error codes would be solving the wrong problem. (a problem of discoverability of the documentation in general)

I could almost see as a more generic alternative to this adding some discoverable header in our response, something like "x-api-docs" with the link to the root of our documentation... that way people who would be served by a specific link by above (i.e. people who didn't already know about our docs) might be able to discover it. Hmm... that could be useful, but I'd have to think about it. That'll be something perhaps for another Issue request!

[floatingatoll]

There surely has to be some project somewhere that is all about the space
of JSON objects and their self-documenting properties, but I don't have any
thoughts of generalizing this. The raw JSON error codes are seen by every
API developer without exception at some point in their app build and
release process, so it's a 100% certainty that you'll successfully deliver
a link to the API error codes docs at that time — which coincidentally then
provides certainty that they know where the official API docs are.

The problems around discoverability of docs are absolutely real for this
API, with multiple various docs sites addressing various revisions of the
API. I wouldn't take it any further than that. Errors are for humans,
Responses are for machines, and the URL is purely for humans, so.

On Tue, Oct 24, 2017 at 11:07 AM, Vendal Thornheart <
[email protected]> wrote:

I don't know - we'd have to ask ourselves how far we take something like
that and how useful it'd actually be to someone. If we start adding
documentation links for that, what makes error code documentation more
important than, say, adding a link to the documentation for some result
property that's hard to understand? And ideally, if people wanted to know
what the result codes were, they could look up the API docs for the method
that they were calling and they should see the link to the result codes
right there in the docs (as is the case for other properties that we
return). The only people who couldn't do that would be people who don't
know the docs exist at all: but at that point, I think adding a
documentation link specifically for the error codes would be solving the
wrong problem. (a problem of discoverability of the documentation in
general)

I could almost see as a more generic alternative to this adding some
discoverable header in our response, something like "x-api-docs" with the
link to the root of our documentation... that way people who would be
served by a specific link by above (i.e. people who didn't already know
about our docs) might be able to discover it. Hmm... that could be useful,
but I'd have to think about it. That'll be something perhaps for another
Issue request!

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
https://github.com/Bungie-net/api/issues/257#issuecomment-339080467, or mute
the thread
https://github.com/notifications/unsubscribe-auth/AAFqDNMMf1sb0EuGM6tF9AjQG_0DFJJxks5svidegaJpZM4QEtsV
.

[vthornheart-bng]

That's a good point - I do agree that particularly errors like InvalidParameters exist as hints to humans who may be making malformed requests. I'll mull it over.

[vthornheart-bng]

Phew, so this is a very, very old error but it finally came up as part of some other work.

Turns out there's many places where we weren't returning more detailed data about errors you encountered - for instance, which parameters were causing errors with an InvalidParameters response.

The next time we deploy, you should start getting better responses back - the "MessageData" property will finally begin to be populated correctly with data that we intended to pass back. The key will be the name of the property we ran into problems with, and the value is a string hinting you at what went awry.

There's likely many places where we still won't actually be returning this data, but this fix will make it much easier for us to make changes that will give you that data. If you see places where you wish you had more data about what failed, let us know!