Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[SC-4051] Revise descriptions of error responses #13

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

[SC-4051] Revise descriptions of error responses #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions openapi/sms/v1/common.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,15 +103,17 @@ components:
schema:
$ref: '#/components/schemas/InvalidFormatErrorBatch'
AuthenticationFailedResponse:
description: Authentication failed - Invalid or missing OAuth token
description: Authentication failed - Invalid or missing OAuth token.
AuthorizationFailedResponse:
description: Authorization failed - OAuth client ID does not have access to this resource
description: Authorization failed - OAuth client ID is not setup correctly or does not have access to this resource.
AuthorizationFailedResponseEmarsys: # Wrong Emarsys environment could try to access something
description: Authorization failed - Emarsys OAuth client ID does not have access to this resource.
ClientDoesNotExistResponse:
description: Client does not exists
description: Client does not exist.
TooManyRequestsResponse:
description: Too many requests
description: Too many requests. Treated as retryable.
ServerErrorResponse:
description: Server error occurred
description: Server error occurred. Treated as retryable.
content:
application/json:
schema:
Expand Down
8 changes: 4 additions & 4 deletions openapi/sms/v1/partner-callbacks.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,13 +32,13 @@ paths:
'202':
$ref: './common.yaml#/components/responses/AcceptedResponse'
'400':
$ref: './common.yaml#/components/responses/InvalidFormatResponse'
$ref: './common.yaml#/components/responses/InvalidFormatResponse' # client id is missing or not a UUID or not a version 4 UUID, or request body violates this spec
'401':
$ref: './common.yaml#/components/responses/AuthenticationFailedResponse'
$ref: './common.yaml#/components/responses/AuthenticationFailedResponse' # oauth token missing or invalid
'403':
$ref: './common.yaml#/components/responses/AuthorizationFailedResponse'
$ref: './common.yaml#/components/responses/AuthorizationFailedResponse' # oauth token succeeds, but no partner with oauth client id is found, or customer connection data client id belongs to a different partner
'404':
$ref: './common.yaml#/components/responses/ClientDoesNotExistResponse'
$ref: './common.yaml#/components/responses/ClientDoesNotExistResponse' # no customer with this client id
'429':
$ref: './common.yaml#/components/responses/TooManyRequestsResponse'
'5XX':
Expand Down
34 changes: 25 additions & 9 deletions openapi/sms/v1/partner-service.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ paths:
'401':
$ref: './common.yaml#/components/responses/AuthenticationFailedResponse'
'403':
$ref: './common.yaml#/components/responses/AuthorizationFailedResponse'
$ref: './common.yaml#/components/responses/AuthorizationFailedResponseEmarsys'
'5XX':
$ref: './common.yaml#/components/responses/ServerErrorResponse'
get:
Expand Down Expand Up @@ -120,7 +120,7 @@ paths:
'401':
$ref: './common.yaml#/components/responses/AuthenticationFailedResponse'
'403':
$ref: './common.yaml#/components/responses/AuthorizationFailedResponse'
$ref: './common.yaml#/components/responses/AuthorizationFailedResponseEmarsys'
'5XX':
$ref: './common.yaml#/components/responses/ServerErrorResponse'
/clients/{clientId}/messages:
Expand All @@ -143,22 +143,38 @@ paths:
'400':
description: |
Returns error type and error context globally, for all messages, or per message.

This should be returned for most errors related to the sending itself. For errors with the Emarsys to partner connection, return the other status codes.

Use the OutboundMessageBatchGlobalError schema if there is an issue with the payload as a whole, and use the OutboundMessageBatchMessageSpecificError response schema if any of the messages are invalid.
Use the OutboundMessageBatchGlobalError schema if there is an issue with the message sending as a whole, and use the OutboundMessageBatchMessageSpecificError response schema if any of the individual messages submitted are invalid.

No messages should be sent or processed if the payload is invalid in any way, even if there are some valid messages among the invalid ones.
No messages should be sent or processed if the payload is invalid in any way, even if there are some valid messages among the invalid ones. By returning a 400, we can rely on no messages having been sent for this request.

Upon recieving a OutboundMessageBatchMessageSpecificError response, the Emarsys SMS Service will treat all of the messages with errors as failed and will retry any messages that did not have errors.
Upon recieving a OutboundMessageBatchMessageSpecificError response, the Emarsys SMS Service will treat all of the messages with errors as failed and will retry any messages that did not have errors, if applicable.

Some examples:

- If the client's credentials are not accepted by the provider, you should return a globalError with an errorType of client.

- If the message is missing a required property, you should return this with an errorType of emarsys.

- If the provider rejects the message immediately, you should return this with an errorType of provider.

- If the destination is not a valid phone number, you should return messageSpecificErrors with an errorType of client.

- If the source is provided but contains an impermissible value, you should return messageSpecificErrors with an errorType of client.

- [I need an example for when you would use the partner errorType] !!!placeholder!!!
content:
application/json:
schema:
$ref: '#/components/schemas/OutboundMessageBatchError'
$ref: '#/components/schemas/OutboundMessageBatchError' # The whole payload is malformed, or some messages within the payload are malformed
'401':
$ref: './common.yaml#/components/responses/AuthenticationFailedResponse'
$ref: './common.yaml#/components/responses/AuthenticationFailedResponse' # Emarsys submits a missing or invalid Oauth token
'403':
$ref: './common.yaml#/components/responses/AuthorizationFailedResponse'
$ref: './common.yaml#/components/responses/AuthorizationFailedResponseEmarsys' # This Emarsys Oauth token does not have access to that resource, <s>or the client credentials are not accepted by the provider</s>
'404':
$ref: './common.yaml#/components/responses/ClientDoesNotExistResponse'
$ref: './common.yaml#/components/responses/ClientDoesNotExistResponse' # No credentials match the client id
'429':
$ref: './common.yaml#/components/responses/TooManyRequestsResponse'
'5XX':
Expand Down