Status Code Definitions
Introduction
This document guides the user on the different types of status codes a developer might see when calling T-Mobile's APIs and their definitions. Status codes can be in the form of:
- Standard HTTP Status Codes
- Apigee Status Codes
- T-Mobile Custom Status Codes
All three are described below.
Standard HTTP Status Codes
General HTTP Status Code Definitions
Some of T-Mobile APIs communicate errors through standard HTTP status codes with details supplied in JSON objects. Generally the following pattern applies:
Status Code |
Definition General Pattern |
---|---|
2xx |
Received, understood, and accepted a request. |
3xx |
The user agent must take further action in order to complete the request. |
4xx |
An error occurred in handling the request. The most common cause of this error is an invalid parameter. |
5xx |
Received and accepted the request, but an error occurred in the T-Mobile service while handling it. |
Specific HTTP Status Code Definitions
Specific HTTP status codes and what likely caused the response can be found below.
Status Code |
Definition / Response |
What Most Likely Caused the Response |
---|---|---|
200 |
success |
The request was successful. |
201 |
created |
The request was successful and the resource was created. |
202 |
accepted |
The request has been accepted for processing, but has not yet been completed. |
204 |
no_content |
The request was successful, but the client does not need to navigate away from the current page. |
302 |
redirect |
The resource has moved. |
304 |
not_modified |
The request has not changed since the last time it was accessed. |
400 |
bad_request |
Invalid/missing data. |
401 |
unauthorized |
Invalid/missing credentials. |
403 |
forbidden, access_denied |
Client does not have access to the requested resource. |
404 |
not_found |
The resource doesn't exists, ex. invalid/non-existent user id. |
405 |
method_not_allowed |
Method not supported by the target. |
409 |
conflict |
Trying to overwrite a resource, ex. when creating a user with an email that already exists. |
412 |
precondition_failed |
Access denied. The client has failed a precondition. |
415 |
unsupported_media_type |
Payload format not supported. |
429 |
too_many_requests |
The number of requests exceeds rate limit. |
500 |
internal_server_error |
Internal server error. |
501 |
not_implemented |
The server does not have the requested resource or method implemented. |
502 |
bad_gateway |
Bad Gateway |
503 |
service_unavailable |
Server is unavailable. |
504 |
gateway_timeout |
Gateway did not get a response in time |
Error Response Example
{
"code": "403",
"userMessage": "Access Denied",
"systemMessage": "Access Denied",
"detailLink": "http://aaa.bbb.ccc/"
}
Error Response Example Schema
Name |
Type |
Description |
---|---|---|
code |
string |
HTTP status code. |
userMessage |
string |
A human-readable message describing the error. |
systemMessage |
string |
Text that provides a more detailed technical explanation of the error. |
detailLink |
string |
Link to custom information providing greater detail on error(s). |
Apigee Status Codes
For APIs that use Apigee as a gateway (endpoint of https://api.t-mobile.com/oauth2/v6/tokens) the following status codes apply.
Apigee Success Responses
Status Code |
Definition / Response |
Description |
---|---|---|
200 |
OK / Success |
Success. The API call was successful. |
201 |
Created |
The request has succeeded and a new resource has been created as a result. This is typically the response sent after POST requests or some PUT requests. |
204 |
No Content |
There is no content to send for this request, but the headers may be useful. The user-agent may update its cached headers for this resource with the new ones. |
Apigee Client Error Responses
Status Code |
Definition / Response |
Description |
Example Response |
---|---|---|---|
401 |
Invalid Access Token |
This error occurs when the access token sent by the client is not valid. |
|
Invalid API Key | An API key was received by Edge, but it is invalid. When Edge looks up the key in its database, it must exactly match the one that was sent in the request. If the API worked previously, make sure the key was not regenerated. If the key was regenerated, you will see this error if you try to use the old key. For details, see Register apps and manage API keys |
|
|
Invalid API Key For Given Resource |
An API key was received by Edge, and it is valid; however, it does not match an approved key in the Developer App associated with your API proxy through a Product. |
|
|
Invalid PoP Token |
This error occurs when the value of the PoP token sent in the X-Authorization header is expired. |
|
|
403 |
IP Denied Access |
The client IP address, or an IP address passed as part of the X-Forwarded-For HTTP header in the API request, matches an IP address specified in the <SourceAddress> element within the <MatchRule> element of the Access Control Policy, and the action attribute of the <MatchRule>element is set to DENY. |
|
406 |
Fault Not Acceptable |
This error occurs when the request.verb is not equal to options and request.header. Accept is not equal to application/xml, application/json, and text/xml |
|
429 |
Quota Violation |
The quota limit was exceeded. |
|
429 |
Spike Arrest Violation |
The rate limit was exceeded. |
|
Apigee Server Error Responses
Status Code |
Definition / Response |
Description |
Example Response |
---|---|---|---|
500 |
General |
The 500 Internal Server Error could be thrown due to a number of different causes. For further details and troubleshooting steps, please refer to this documentation. |
|
Failed To Resolve Quota Interval Reference |
Occurs if the |
|
|
Failed To Resolve Quota Interval Time Unit Reference |
Occurs if the |
|
|
Failed To Resolve Spike Arrest Rate | This error occurs if the reference to the variable containing the rate setting within the |
|
|
501 |
Unknown Resource |
This type of error occurs when none of the conditional flows are matched. The server does not support the functionality required to fulfill the request. |
|
502 |
Bad Gateway |
This error response means that the server, while working as a gateway to get a response needed to handle the request, got an invalid response. For further details and troubleshooting steps, please refer to this documentation. |
|
Bad Gateway Timeout |
The Message Processor returns this error to the client application when it does not receive a response from a backend server. For further details and troubleshooting steps, please refer to this documentation. | ||
Bad Gateway Unexpected EOF |
The HTTP status code 502 means that the client is not receiving a valid response from the backend servers that should actually fulfill the request. For further details and troubleshooting steps, please refer to this documentation. |
||
503 |
Service Unavailable | The HTTP response 503 Service Unavailable with the error code messaging.adaptors.http.flow.ServiceUnavailable occurs if the Apigee Edge’s Message Processor experiences errors due to connection time out, incorrect host name, or SSL handshake failures while communicating with the backend server. Additional details and troubleshooting steps here. |
|
Service Unavailable - Backend Server |
The HTTP status code 503 means that the server is currently unable to handle the incoming requests. Usually, this error occurs because the server is too busy or is temporarily down for maintenance. Additional details and troubleshooting steps here. |
||
Service Unavailable - No Active Targets |
The HTTP response 503 Service Unavailable with the error code NoActiveTargets is typically observed when you use one or more target servers in the target endpoint configuration in your API Proxy. Additional details and troubleshooting steps here. |
||
504 |
Gateway Timeout |
The HTTP status code - 504 Gateway Timeout error indicates that the client did not receive a timely response from the Edge Gateway or backend server during the execution of an API. Additional details and troubleshooting steps here. |
NaaS
Error codes for any APIs that use the https://naas.t-mobile.com/oauth2/v2/tokens endpoint.
Example Status Code Response |
Description |
What Most Likely Caused the Response |
---|---|---|
|
You API key is invalid. |
|
|
The PoP token is invalid. |
|
|
One of your tokens is invalid. |
|
|
Your PoP Token, or x-authorization, header is missing. |
|
|
This HTTP 409 status code means that the resource that you are trying to create already exists. |
|
|
This 401 error means that your OAuth 2.0 access token has expired. Access tokens are only viable for 3600 seconds but can, however, be used for multiple hops and on multiple API calls. |
|
|
This 401 error is similar to 403 Forbidden, but specifically for use when authentication is possible but has failed or not yet been provided. The response must include a WWW-Authenticate header field containing a challenge applicable to the requested resource. |