Errors

400 Bad Request

Returned when the request contains invalid parameters or fails schema validation. A 400 response is a JSON object with an errors array (and an optional meta object).

Fields

Example

{
  "errors": [
    {
      "field": "manager.managerEmailAddress",
      "message": "Manager email address must be filled"
    },
    {
      "message": "This endpoint has been sunset and is no longer supported."
    }
  ]
}

Common Causes

• Missing required parameters
• Invalid parameter format (e.g., invalid date, malformed email)
• Schema validation failure
• Malformed request headers
• Calling a sunset endpoint (see Deprecation)

401 Unauthorized

Returned when the access token is missing, expired, or invalid. The response body is a JSON object with a single error object.

Fields

Example

{
  "error": {
    "message": "The access token is invalid"
  }
}

Common Causes

• Missing Authorization header
• Expired access token
• Revoked access token
• Malformed token format

Example Messages

The exact message text may vary. Typical values include:

• The access token is invalid
• The access token expired
• The access token was revoked
• The access token is missing

Resolution

Obtain a new access token using your OAuth credentials.

403 Forbidden

Returned when the access token is not permitted to use the endpoint or perform the action. A 403 response is a JSON object with an error object.

Fields

Example

{
  "error": {
    "message": "Access to this resource requires scope \"manage\"."
  }
}

Common Messages

Resolution

• Verify your OAuth application has the required scopes
• Contact support if your account appears to be restricted

404 Not Found

Returned when the requested resource does not exist or the access token does not have access to view it.

Response

This response has an empty body.

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 0

Common Causes

• Resource ID does not exist
• Access token lacks permission to view the resource

422 Unprocessable Entity

Returned when the request is structurally valid but fails business logic validation. The response body is a JSON object with an errors array (and an optional meta object).

Fields

Example

{
  "errors": [
    {
      "field": "email",
      "type": "INVALID",
      "message": "Email is not valid"
    },
    {
      "message": "Operation is not allowed in the current state"
    }
  ]
}

Common Error Types

This list covers the most common values. Other UPPER_SNAKE_CASE tokens may appear for endpoint-specific validations.

Difference from 400

• 400 Bad Request: Schema/format validation (e.g., "startDate must be a date")
• 422 Unprocessable Entity: Business logic validation (e.g., "start date must be in the future")

429 Too Many Requests

Returned when you exceed the API rate limits.

Response

This response has an empty body but includes rate limit headers.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 45
RateLimit-Limit: 300
RateLimit-Window: 300

Headers

500 Internal Server Error

Returned when an unexpected error occurs on the server. The response body is a JSON object with a single error object.

Fields

Example

{
  "error": {
    "code": "OY99",
    "message": "Internal server error"
  }
}

Resolution

• Retry the request after a short delay
• If the error persists, contact Oyster API Support and provide:
  • The error code from the response
  • The endpoint you were calling
  • The approximate time the error occurred

Error Response Summary